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 Githome,
• 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

• 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, Githome asks you to confirm with your passkey first.

#Set up a Claude Code cloud environment

1. Open the repository on Githome, then Settings → Agent setup (https://git.pkgforge.dev/<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 git.pkgforge.dev under Allowed domains, and keep Also include default list of common package managers ticked. Full works too. The default Trusted level doesn't include git.pkgforge.dev.

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

   curl -fsSL https://git.pkgforge.dev/<owner>/<repo>/agent-setup.sh | bash

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

   GITHOME_TOKEN=ghome_…
   GH_ENTERPRISE_TOKEN=ghome_…
   GH_HOST=git.pkgforge.dev
   GITHOME_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>, and these all work with no prompt and no path prefix:

githome --version
githome whoami
git clone https://git.pkgforge.dev/<owner>/<repo>.git
gh api user --hostname git.pkgforge.dev --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 githome setup (Install and sign in to the CLI). Workflows get their own token automatically on a deployment where CI runs (Workflow permissions); the forge CI of git.pkgforge.dev is dormant.

#What the setup script does

The script is the same for everyone, with the repository's name in it, and holds no secret: open its URL (box 3 of the page) in a browser and read it before you use it. It runs these steps, in order:

1. Installs the githome CLI and puts it on PATH (/usr/local/bin/githome 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 GITHOME_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 githome setup --repo <owner>/<repo>, which:
   • makes git use the token for git.pkgforge.dev (githome auth setup-git): git asks the CLI, which reads GITHOME_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 GITHOME_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 GITHOME_CLONE_DIR to choose, or GITHOME_NO_CLONE=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 .githome/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 Githome 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 a security email about a created token is sent only where the deployment's email sending is set up.

#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 githome setup --repo <owner>/<repo>.

#For AI agents reading this page

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

• githome 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 GITHOME_TOKEN isn't set, ask the person to open the repository's Settings → Agent setup on Githome and paste its boxes into your environment's settings.
• Open pull requests with githome pr create --intent or gh pr create. You may merge only what a person approved; see Merging.
• The REST API reports the Check at GET /api/v3/repos/<owner>/<repo>/githome/agent-setup.