Start / reusable configuration

Connections and profiles

Save credentials without putting them in a workflow, then reuse the same run settings from your account or across an organization.

What each one stores

A profile saves two JSON documents. GraphSpec says which steps run, while RuntimePlan chooses the model and connection fields for every executable step. A connection holds the private values for those fields; profiles contain neither credentials nor task input.

One RuntimePlan node

Zeroshot

{
  "kind": "agent",
  "model": "gpt-5.6-sol",
  "connections": {
    "openai": ["OPENAI_API_KEY"]
  }
}

This node asks for OPENAI_API_KEY from the connection named openai. The profile stores those names, while the API key itself stays in the connection store.

For this example, Platform resolves the whole openai connection from one source. It never takes one field from the run process and another from a saved connection.

`Run process`	If the process supplies every declared field, those explicit values win for this run.
`User connection`	When the process supplies none of the fields, Platform checks your saved connection first.
`Org connection`	If no user connection exists, Platform checks the organization connection with the same name.
`Partial values`	Platform rejects a partial explicit connection instead of borrowing the missing fields.

Read the connection value rules

Manage connections

Open your organization in the Platform console, then choose Connections. Save a credential on the User tab when it belongs to you; use the Org tab for a shared credential.

`User`	Runs you start can use it. If the organization has a connection with the same name, your user connection takes priority.
`Org`	Organization members can use it in their runs, but nobody can read back the saved values. Only owners and admins can replace or delete it.

Connection types

Choose the Anthropic, OpenAI, or OpenRouter row to save that provider's API key.
Choose Amazon Bedrock to save a Bedrock API key and the AWS region where Platform should check and use it. Replacing either value requires entering both again.
Choose Gateway to save an endpoint as GATEWAY_BASE_URL and its API key as GATEWAY_API_KEY. The endpoint must expose the Responses API for codex or the Messages API for claude.
Connect your GitHub account before you start a Platform run. For organization repositories and issue comments, an administrator must also install the organization GitHub App.
Choose a custom static connection when your workflow needs other environment values. Give the connection a name, then add the field names and values it should hold.

A runtime or profile uses the saved Bedrock values by choosing bedrock as its provider and declaring bedrock with AWS_BEARER_TOKEN_BEDROCK and AWS_REGION as the connection. Bedrock supports both the codex and claude harnesses; choose the model separately in the runtime binding.

Gateway also supports both harnesses. Choose gateway, declare the two Gateway fields on the gateway connection, and enter any model ID accepted by that endpoint; Platform does not restrict Gateway model IDs to a catalog.

For Copilot, connect your GitHub account on the User tab and use your personal Copilot subscription. Choose copilot as the harness and github as the provider. Declare COPILOT_GITHUB_TOKEN and COPILOT_GITHUB_TOKEN_EXPIRES_AT on the github connection so Platform can refresh the credential during a run. A connected GitHub account does not confirm Copilot entitlement. Organization-only issue runs cannot use this personal connection.

Run a CLI connection command without --target to use the local connection store. Connections saved there do not appear in the Platform console.

Pi gateway connections

On a target with Pi support, choose pi as the harness and gateway as the provider. Save a custom static connection named pi_gateway with the endpoint, API key, and wire protocol fields shown below. Use this distinct name so the connection stays in the custom list; the built-in Gateway form saves only the endpoint and key.

Set GATEWAY_API to openai-responses, openai-completions, or anthropic-messages to match your endpoint. Each Pi gateway node must declare all three fields under the same custom connection name. The values stay in the connection store; this uniform runtime configuration contains only their names:

Pi gateway uniform runtime configuration

Zeroshot

{
  "harness": "pi",
  "provider": "gateway",
  "model": "YOUR_PROVIDER_MODEL_ID",
  "connections": {
    "pi_gateway": [
      "GATEWAY_BASE_URL",
      "GATEWAY_API_KEY",
      "GATEWAY_API"
    ]
  }
}

Connect GitHub

Every person who starts Platform runs must connect their own GitHub account. When the repository belongs to a GitHub organization, a Zeroshot organization owner or admin must also install the Zeroshot GitHub App and grant it access to that repository.

The account connection identifies the person who submitted the run. The App gives Platform short-lived credentials limited to the repositories and permissions approved in GitHub. Once both are connected, Platform can work with private repositories and deliver a pull request; the App also accepts issue commands.

Connect your account and install the App

`Your GitHub account`	This is the Platform equivalent of `gh auth login`. A run you start can use your GitHub identity, so every person who starts Platform runs must connect their own account.
`Organization GitHub App`	An administrator installs this shared integration on the organization's repositories. It gives Zeroshot access only to the repositories you select and accepts issue commands such as `@zeroshot-cloud run`. One installation covers the Zeroshot organization.

Set up both connections

Connect your GitHub accountOpen Connections, stay on the User tab, and choose Connect under GitHub account. Approve the request on GitHub. Platform now has its own account connection; your local gh login does not change.
Have an administrator install the AppOn the Org tab, choose Install App. The person installing it must be a Zeroshot organization owner or admin, and GitHub must let that person install apps for the chosen repositories. A GitHub organization owner usually has this access; a repository admin can install the App only when organization policy permits it.
Choose the repositoriesSelect the GitHub organization, then grant access to all repositories or a smaller list. After GitHub returns you to Connections, the GitHub App row should read Connected. Choose Configure App later if the repository list needs to change.

Review the requested access

Read the permission list on GitHub before you approve the installation. Zeroshot requests repository permissions only; the App receives no organization-level permissions.

`Selected repositories`	Choose all repositories or a smaller list. If Zeroshot needs only part of the organization, grant access to those repositories instead of the full set.
`Contents: read and write`	A run can check out the repository, create its working branch, and push the completed changes.
`Pull requests: read and write`	Zeroshot can open the delivery pull request or update one it already created.
`Checks and statuses: read`	A run can read the current CI checks and commit statuses before it continues.
`Actions: read`	When a GitHub Actions check fails, a run can read that job's log to fix the failure.
`Issues: read and write`	Zeroshot can read the issue, accept a trusted `@zeroshot-cloud run` command, react to the command comment, and post progress or result comments.

GitHub command reference GitHub App installation requirements GitHub organization app policies

Manage profiles

Open Profiles in the organization console and choose the User or Org tab. Select a profile to edit its graph and runtime in the workspace, or choose New profile. Profiles contain graph and agent settings. Choose the environment separately when submitting a run. You can also import a profile JSON file. Choose Save profile when ready; a different name saves a copy. Set the saved profile as the default for submissions that omit a name.

`User`	Only you manage it. If an organization profile has the same name, your user profile takes priority.
`Org`	Every organization member can use it. Only owners and admins can change or delete it.

Every new organization starts with an Org profile named default that runs thesoftware-change workflow. Editing or deleting a profile affects only later submissions because an accepted run keeps its own copy of the graph and runtime settings.

Quick run lists User and Org profiles separately. After choosing a repository, select Default, Base, or a saved environment. Default uses your repository default, then the organization default, then Base. Profiles remain portable between repositories and environments. Open Environments, choose User or Org, and select a repository to manage its scripts, variables, and preparation connections. User repositories come from your GitHub connection; Org repositories come from that organization's GitHub App. Each repository can have several saved environments. Set or clear a default for the selected scope; deleting a default clears it. New runs use the latest selected definition, while accepted runs and resumes retain their saved copy. Read the setup and startup contract.

Run a CLI profile command without --target to manage local profiles. They stay on that machine and do not appear in the Platform console.

Run a profile

Add --profile instead of passing graph, template, runtime, or delivery options. Prefix the profile name with local:, user:, or org: when you need one exact scope.

Save the runtime settings below as profile-runtime.json, then create the organization profile. To run the example, reuse input.json from the Quickstart.

profile-runtime.json

Zeroshot

{
  "harness": "codex",
  "provider": "openai",
  "model": "gpt-5.6-sol",
  "connections": {"openai": ["OPENAI_API_KEY"]}
}

Create profile

Zeroshot

zeroshot profile set small-change \
  --target platform \
  --scope org \
  --template single-worker \
  --uniform-runtime-config ./profile-runtime.json

Platform run

Zeroshot

zeroshot run \
  --target platform \
  --title "Update the README" \
  --profile org:small-change \
  --input ./input.json

With --target, a profile name without a prefix checks the local store first, your user profiles next, and organization profiles last. Default profiles use that same order. Without --target, Zeroshot checks only local profiles; user: and org: are invalid in that mode.

Run from a GitHub issue or PR

Once an administrator installs the GitHub App, comment @zeroshot-cloud run on an issue to use the organization's default profile. A command such as @zeroshot-cloud run review uses the organization profile named review. Review profiles also accept commands on PR conversations.

Read the GitHub command reference