Connections and profiles | Zeroshot Cloud

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, Cloud 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, Cloud checks your saved connection first.
`Org connection`	If no user connection exists, Cloud checks the organization connection with the same name.
`Partial values`	Cloud rejects a partial explicit connection instead of borrowing the missing fields.

Read the connection value rules

Manage connections

Open your organization in the Cloud 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.
Connect your GitHub account before you start a Cloud 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.

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

Connect GitHub

Every person who starts Cloud 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 Cloud short-lived credentials limited to the repositories and permissions approved in GitHub. Once both are connected, Cloud 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 Cloud equivalent of `gh auth login`. A run you start can use your GitHub identity, so every person who starts Cloud 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. Cloud 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. Administration is read-only and lets Cloud inspect branch protection before a merge-plan run starts.

`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.
`Administration: read`	Cloud checks the target branch protection before it releases a merge-plan run.
`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.
`Issues: read and write`	Zeroshot can read the issue, accept a trusted `@zeroshot-cloud run` command, add a reaction when work starts, and post progress or result comments.

GitHub issue 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. Create the profile with complete GraphSpec and RuntimePlan JSON. Set it as the default if a run should use it when the submission does not include a profile 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 a default software-change profile. Editing or deleting a profile affects only later submissions because an accepted run keeps its own copy of the graph and runtime settings.

Run a CLI profile command without --target to manage local profiles. They stay on that machine and do not appear in the Cloud 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 cloud \
  --scope org \
  --template single-worker \
  --uniform-runtime-config ./profile-runtime.json

Cloud run

Zeroshot

zeroshot run \
  --target cloud \
  --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

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.

Read the GitHub issue command reference