Cloud agent environments

A cloud agent runs in a sandbox that starts fresh: a Claude Code cloud environment, Codex in the cloud, or any other agent platform. Settings → Agent setup on a repository gives it everything it needs to work on that repository from its first session, with no manual wiring:

• a token that reaches only that repository,
• the domain to allow,
• a one-line setup script hosted on Diffinery,
• the environment variables, with the token filled in,
• and a Check that turns green once a session has set itself up and passed a self-test.

Then the agent can clone, push branches, open pull requests and use gh against the repository. The page is the same for every agent platform: each one asks for the same three things.

#Before you start

• On a self-hosted Diffinery, everything below works the same with your instance's domain in place of diffinery.com: its Agent setup page shows the setup script and environment variables with its own URLs, and the network setting must allow its domain.

• You need write access to the repository. Admins find Agent setup among the repository's settings; people with write access get a Settings tab that opens it.

• Generating a token needs a passkey sign-in from the last 2 hours, as for any token. If yours is older, Diffinery asks you to confirm with your passkey first.

#Set up a Claude Code cloud environment

1. Open the repository on Diffinery, then Settings → Agent setup (https://diffinery.com/<owner>/<repo>/settings/agent-setup).

2. Choose Generate agent token. Change the label if you like, so you can tell environments apart later. The token appears once, already filled into box 4.

3. In Claude Code, open the environment selector under the message box at claude.ai/code, and edit the environment (the settings icon on its row) or add a new one. The Edit cloud environment dialog has the three fields to fill.

4. Network access: choose Custom, put diffinery.com under Allowed domains, and keep Also include default list of common package managers ticked. Full works too. The default Trusted level doesn't include diffinery.com.

5. Setup script: paste box 3, which looks like this:

   curl -fsSL https://diffinery.com/<owner>/<repo>/agent-setup.sh | bash

6. Environment variables: paste box 4 as it is:

   DIFFINERY_TOKEN=dfy_…
   GH_ENTERPRISE_TOKEN=dfy_…
   GH_HOST=diffinery.com
   DIFFINERY_REPO=<owner>/<repo>

7. Save, and start a session in the environment. Back on the Agent setup page, the Check turns green within seconds of the setup script finishing (the page updates by itself).

In the session, the repository is cloned at /home/user/<repo>, Claude Code has the Diffinery plugins (so Claude hears when CI on its pushed commit passes or fails), and these all work with no prompt and no path prefix:

diffinery --version
diffinery whoami
git clone https://diffinery.com/<owner>/<repo>.git
gh api user --hostname diffinery.com --jq .login
gh pr list --state all          # inside the clone

#Other agent platforms

Every agent sandbox has the same three settings under its own names:

On a machine you already work on, you don't need any of this: install the CLI and run diffinery setup (Install and sign in to the CLI). Workflows on Diffinery Actions get their own token automatically (Workflow permissions).

#What the setup script does

The script is the same for everyone, with the repository's name in it, and holds no secret: read it before you use it. It runs these steps, in order:

1. Installs the diffinery CLI and puts it on PATH (/usr/local/bin/diffinery when it runs as root, as in Claude Code). It skips the download when the installed CLI is already the server's current build, so later runs take a few seconds.
2. Stops with a clear message if DIFFINERY_TOKEN isn't set, after setting up what it can: git is then ready to use the token as soon as it is in the environment.
3. Runs diffinery setup --repo <owner>/<repo>, which:
   • makes git use the token for diffinery.com (diffinery auth setup-git): git asks the CLI, which reads DIFFINERY_TOKEN from the environment each time. The token is never written to disk, so no snapshot or file holds it.
   • leaves gh to GH_ENTERPRISE_TOKEN and GH_HOST from the environment. Without them it signs gh in with DIFFINERY_TOKEN instead (gh then keeps it in its own config).
   • clones the repository unless it's there already, or fetches it when it is. It goes in /home/user/<repo> in a Claude Code cloud environment and in the current directory elsewhere; set DIFFINERY_CLONE_DIR to choose, or DIFFINERY_NO_CLONE=1 to skip it.
   • adds Claude Code's Diffinery plugins, diffinery and diffinery-ci, so sessions in the environment load them: Claude then hears when CI on a commit it pushed passes or fails (CI status in Claude). Set DIFFINERY_NO_CLAUDE_PLUGINS=1 to skip it.
   • checks each part and prints one line per check, saying what to change when one fails.
   • reports the result to the repository's Check.

It is fully non-interactive, never prints the token, and is safe to run at the start of every session. It exits with 1 when the CLI can't be installed or a check fails, so a broken setup isn't kept in a snapshot and the session's setup log shows why.

#The token

Each person gets their own agent for each repository the first time they generate a token there: an agent account named after the repository, such as zutrix-agent. Its commits, comments and pull requests show as the agent's, acting for you.

#Merging

With Can merge pull requests on (the default), the agent may merge a pull request, or turn on auto-merge for it, once:

• a person has approved the pull request's latest commit: agents' own reviews never count, and a push after the approval needs a new one;
• every rule of the branch is met: required approvals, required checks, linear history, the merge queue;
• the pull request doesn't change a workflow file (.github/workflows/ or .diffinery/workflows/): those always need a person to merge, because CI can't vouch for a change to itself.

Turn it off on the page and the agent can't merge into the default branch or a protected one at all; a person merges. Rules on the branch itself still apply either way, such as Allow agents to land pull requests through auto-merge in Branch protection.

Merge its pull requests on green (offered under Label when you generate the first token, and next to Can merge pull requests afterwards) has Diffinery turn on auto-merge for each pull request the agent opens, so it lands by itself once the default branch's required checks pass: right away where the repository waives the approval through Merge on green, otherwise once a person approved its latest commit. The text under the box says which applies in this repository. It needs at least one required check on the branch, and a workflow change still needs a person.

#Renew, revoke and regenerate

• Renew keeps a token working for 90 days from today.
• Revoke and regenerate stops the token at once and makes a new one, filled into box 4 for you to paste. Use it whenever a token may have leaked.
• Revoke stops it.
• Admins of the repository see everyone's agents for it on the page and can turn any of them off, which revokes their tokens.

Every token change is in the audit log (agent_setup.token.create, .regenerate, .renew, .revoke), and you get the usual email when a token is created.

#Keep the token safe

• Environment variables are visible to anyone who uses the environment, so treat the token as shared with them.
• Never paste the token into a chat or a screenshot. If it leaks, choose Revoke and regenerate.
• Claude Code's Network secrets keep a credential outside the session, but they don't reach setup scripts, and gh won't run without a token of its own, so Agent setup uses environment variables.

#When the Check fails

The page shows each failed line with what to change. The usual ones:

Until a session runs the script with every check passing, the Check says Not connected yet. To check again inside a running session, run the setup script again, or diffinery setup --repo <owner>/<repo>.

#For AI agents reading this page

If you are an agent in a sandbox with DIFFINERY_TOKEN set:

• diffinery setup --repo <owner>/<repo> checks your setup and fixes what it can; each failed line says what the person has to change in the environment's settings. Don't try to change those settings yourself.
• If DIFFINERY_TOKEN isn't set, ask the person to open the repository's Settings → Agent setup on Diffinery and paste its boxes into your environment's settings.
• Open pull requests with diffinery pr create --intent or gh pr create, and follow CI with diffinery pr checks --watch. You may merge only what a person approved; see Merging.
• The REST API reports the Check at GET /api/v3/repos/<owner>/<repo>/diffinery/agent-setup.