agent-cloud-kit

A zero-dependency CLI that prepares Claude Code on the web cloud sessions. It installs the tool versions a repo pins, starts Docker, completes the partial clone, and tells you when the saved machine is not what the repo asks for, working around the limits of the cloud sandbox that the platform does not document.

Not affiliated with or endorsed by Anthropic. Works with Claude Code on the web.

Continues @ramon-sg/claude-cloud (its 1.0.0), with no automatic migration: install this package and run init again.

• Written in TypeScript, published compiled, no runtime dependencies, Node >=20 (the cloud image ships Node 22, so it runs before any tool of your repo is installed).
• The repo decides the version: .claude/cloud.json pins the exact version of this package, so updating it is a commit.

What it solves

Installing Node and starting Docker takes a few lines of shell. The expensive part is what the platform does not tell you:

• The egress proxy blocks GitHub releases and GitHub's GraphQL API, so tools that download from GitHub fail. agent-cloud-kit installs Node from nodejs.org; Bun, Deno, pnpm and Yarn from npm; and uv from PyPI.
• The GitHub proxy only serves repos/{owner}/{repo}/… routes of the session's repos. GraphQL (gh pr, gh issue, gh project), Projects v2, search/…, user/repos and other repos get a 403 written by the proxy (This GitHub API path is not available: sessions are bound to their configured repositories…), and your own GH_TOKEN does not change that. For Projects and everything outside the repo, use the GitHub connector of claude.ai, set up once per account (guide); its tools ask for approval on every call until you set them to "always allow" in claude.ai, which a permissions.allow rule in the repo does not replace. docs/agent-cloud.md says what works.
• The setup script runs from /home/user, not from the repo, and a failure is silent.
• A setup that takes more than about 5 minutes does not leave a saved machine.
• Two apt runs at the same time collide on the dpkg lock, so apt work runs in series.
• dockerd is off and the clone is partial (shallow, without origin/<default branch>).
• There is no IPv6.
• The proxy replaces TLS, and docker build does not trust its CA.
• A resumed session does not run the setup again, and changing the setup does not rebuild the saved machine.

The flow

1. Install your agent tooling with agent-kitchen (config, hook and skill arrive in the repo).

2. Run npx agent-cloud-kit prepare in a local terminal. It asks where to work, with the same menu as agent-kitchen (--pr or --here skip it):

   • En un PR nuevo (default): creates a worktree on a dated branch from origin, so your branch and uncommitted files are untouched; runs init, opens Claude locally with the cloud-ready skill so it can write the cloud preparation with you, then writes the manual, commits, pushes and opens a draft PR.
   • En la rama actual, sin commit: does the same in your checkout and stops there; you review with git diff, commit, push, and then run npx agent-cloud-kit verify.

   Before Claude opens, a short screen says what will happen and waits for Enter. If the repo uses claude-repo-guard and has its claude:free script, Claude opens through it, so the skill can write the files the guard blocks.

3. Configure the environment in claude.ai following docs/agent-cloud.md, which prepare generated from your .claude/cloud.json. The document keeps growing: when the skill, locally or in the cloud, finds that a domain or an environment variable is missing, it adds it to .claude/cloud.json, regenerates the document and tells you in the session what to add in claude.ai. If the repo's workflow uses GitHub outside the repo (Projects, search, other repos), also add the GitHub connector in claude.ai and set its tools to "always allow" (see the guide above).

4. Verification in the cloud: prepare (new PR) or verify (current branch, once pushed) launches claude --cloud on that branch, so a real cloud session runs cloud-ready verify, fixes what fails and reports in the PR. Run npx agent-cloud-kit verify again whenever you change the environment.

claude --cloud uses the environment chosen with /remote-env in claude, and the Claude GitHub App must be installed on the repo (without it the session cannot push). Inside the cloud, gh api (REST) works; GraphQL (gh pr list, gh pr create) is blocked. If prepare is interrupted, npx agent-cloud-kit prepare --resume continues in the existing worktree.

No opinion about tests

This package does not impose any way of testing, and a repo may have no tests at all (then the cloud only needs a prepared machine). The cloud-ready skill finds the tests your repo already has, tells you which would run in the cloud as they are, and proposes adapting the cloud preparation or, only if needed, a cloud variant of them. Nothing changes without your approval.

The cloud-ready skill

init copies it to .agents/skills/cloud-ready and links it from .claude/skills/cloud-ready, because Claude Code does not discover .agents/skills. Commit both. cloud-ready configure runs locally with you; cloud-ready verify runs inside the cloud session. The skill and the generated manual are written in Spanish.

Set up claude.ai

In the environment form at https://claude.ai/code:

1. Network access: choose Custom and keep Also include default list of common package managers checked. Add any extra domains your apt repos or setup steps need, one per line. Run agent-cloud-kit doctor in a session to see which hosts are blocked (it probes with curl, so it goes through the proxy like the setup does). If the setup never ran, use npx agent-cloud-kit doctor.

2. Setup script: the cloud runs it as root from /home/user, before Claude starts:

   #!/bin/bash
   npx -y agent-cloud-kit@1 setup

   The @1 only pins the launcher. Each repo then relaunches the exact version it asks for, so a new launcher major is adopted by editing this field on purpose. To force the saved machine to be rebuilt, change anything in this field (a comment with the date works).

3. In each repo run npx agent-cloud-kit init, then commit .claude/cloud.json, .claude/settings.json, .agents/skills/cloud-ready and the .claude/skills/cloud-ready link.

Environment changes are read when a session is created: start a new session to test them. A resumed session does not run the setup again.

.claude/cloud.json

It lives in .claude/ rather than in package.json so repos without Node can use it. A JSON schema ships with the package (schema.json). Unknown fields are reported and ignored, and a broken file never stops a session.

{
  "$schema": "https://unpkg.com/[email protected]/schema.json",
  "version": "1.0.0",
  "aptRepos": ["https://example.com/setup.deb.sh"],
  "apt": ["direnv", "jq"],
  "domains": ["registry.example.com"],
  "docker": { "pull": "auto" },
  "setup": ["scripts/cloud-setup-extra.sh"],
  "session": ["scripts/worktree-setup.sh"],
  "requiredEnv": ["API_TOKEN"],
  "notes": ".claude/cloud-notes.md"
}

| Field | Required | Meaning | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | version | yes | Exact version of this package to run (no ranges). If setup runs a different one it relaunches with this one. | | aptRepos | no | HTTPS URLs of setup scripts that add APT repositories; each is downloaded and piped to bash before installing packages. | | apt | no | Debian packages to install. Names are validated and passed as arguments, never to a shell. | | domains | no | Extra hosts the environment must allow; doctor probes them and the manual lists them. | | docker.pull | no | "auto" (default) pulls the images found in compose files and in FROM lines pinned with @sha256; a list of image names pulls those; false leaves Docker alone during setup. | | setup | no | Shell commands run once during setup, in the repo, with the pinned tools first on PATH. A failing command is recorded and the rest still run. | | session | no | Shell commands run at the start of every session, in the repo. Their output goes to stderr (not into Claude's context), each one is stopped after 2 minutes, and a failing command is reported while the rest still run. | | requiredEnv | no | Environment variables that must be set; the session warns about the missing ones. | | notes | no | What does and does not run in the cloud: free text, or a path, relative to the repo, of a text file inside it (then its contents are used). Printed at the start of every session and shown in the manual. prepare expects the file the cloud-ready skill writes. |

Tool versions are deduced, in order, from .tool-versions, mise.toml, .nvmrc and package.json#packageManager. The default branch comes from origin/HEAD. Each tool is installed under /opt/agent-cloud-kit/<tool>-<version>, so versions coexist and the repos of one environment share the folder. A tool with no installer produces a warning and is skipped.

A Node version that is not exact (22, 22.1, lts/iron, lts/* or node) is resolved during setup to the newest matching release in https://nodejs.org/dist/index.json and installed under /opt/agent-cloud-kit/node-<exact version>. The resolved version is recorded in the machine state, so session puts the same folder on PATH.

Commands

| Command | What it does | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | agent-cloud-kit setup [--repo <path>] | Runs as root before Claude starts. For every git repo in the home dir (/home/user) with a .claude/cloud.json (or only <path>): installs tools, apt packages and images and copies itself (no npm, no network) to /opt/agent-cloud-kit/bin/agent-cloud-kit, then runs the setup steps and records the result. Repos without the file are skipped with a notice. It always exits 0: failures are recorded, never fatal. | | agent-cloud-kit session | Runs from the SessionStart hook, in seconds and without network (except to complete the clone). Warns when setup did not run, failed steps, or the machine was prepared with another configuration; writes the PATH line (the pinned tools, then /opt/agent-cloud-kit/bin, so agent-cloud-kit itself resolves) to $CLAUDE_ENV_FILE; starts Docker; fetches the full history and origin/<default branch>; runs the session steps. It never fails the session start. | | agent-cloud-kit docker | Starts dockerd detached and waits up to 60 seconds for it to answer. Exits 1 if it does not, at once when dockerd is not installed. | | agent-cloud-kit doctor | Checks that the proxy lets the needed hosts through, that the pinned tools are installed, that Docker answers, and the recorded state (fingerprint and each step). Exits 1 if any check fails. | | agent-cloud-kit init | Creates .claude/cloud.json if missing, adds the SessionStart hook to .claude/settings.json (keeping the hooks already there), copies the cloud-ready skill to .agents/skills/cloud-ready when its version differs, and links it from .claude/skills/cloud-ready. Safe to run again. | | agent-cloud-kit manual | Writes docs/agent-cloud.md from .claude/cloud.json, deterministically: the exact setup script (agent-cloud-kit@<major>, or the exact version for a release candidate), domains, variable names, how to verify the environment. | | agent-cloud-kit prepare [--pr\|--here\|--resume] | Local only, needs an interactive terminal: sets the repo up for the cloud, in a new PR or in the current branch without committing (asks when no option is given; see "The flow"). --resume continues in the existing worktree. | | agent-cloud-kit verify | Local only, needs an interactive terminal: launches a cloud session that runs cloud-ready verify on the current branch, which must be prepared and pushed. |

Environment variables: AGENT_CLOUD_KIT_DIR overrides /opt/agent-cloud-kit and AGENT_CLOUD_KIT_HOME overrides /home/user; both exist mainly for tests.

Language and Kuro

The terminal speaks Spanish by default. --lang en (with any command) switches it to English for one run, and AGENT_CLOUD_KIT_LANG=en|es fixes it; --lang wins over the variable. LANG and LC_ALL are not read. Only the terminal changes: what is written in the repo (docs/agent-cloud.md, .claude/cloud-notes.md, the cloud-ready skill, the commit) and the prompts for Claude stay in Spanish. setup passes the language on to the version it relaunches, and session to the one it delegates to.

In a terminal, the final messages (the end of doctor, prepare and verify, and the screen before Claude opens) come in a block with Kuro, the mascot of issue-flow and agent-kitchen. NO_COLOR removes the color and keeps Kuro. Outside a terminal (logs, pipes, the SessionStart hook) the lines keep the plain agent-cloud-kit: prefix.

The SessionStart hook

init adds this hook. Outside a cloud session it does nothing, and it calls the copy of the package that setup left on the saved machine, so it needs no network and no node_modules:

{
  "type": "command",
  "command": "[ \"$CLAUDE_CODE_REMOTE\" = true ] || exit 0; /opt/agent-cloud-kit/bin/agent-cloud-kit session || echo 'agent-cloud-kit: el setup del entorno no corrió; revisa con npx agent-cloud-kit doctor'",
  "timeout": 600
}

When the repo pins another version than the one that is running and that version is installed, session hands over to it.

Machine fingerprint

setup stores a fingerprint of the config, the pinned versions, the images and the package version. If the repo changes afterwards, session warns that "la máquina se preparó con otra configuración". The saved machine is rebuilt by claude.ai about every 7 days, or when you edit the setup script field.

The proxy CA and docker build

The cloud proxy replaces TLS, so docker build does not trust it. session finds the CA bundle (SSL_CERT_FILE, then NODE_EXTRA_CA_CERTS, then /root/.ccr/ca-bundle.crt) and exports its path as CLOUD_PROXY_CA. Pass it to the build as a secret, only when it is set:

docker build ${CLOUD_PROXY_CA:+--secret id=proxy_ca,src="$CLOUD_PROXY_CA"} -t app .

RUN --mount=type=secret,id=proxy_ca \
    if [ -f /run/secrets/proxy_ca ]; then \
      export SSL_CERT_FILE=/run/secrets/proxy_ca NODE_EXTRA_CA_CERTS=/run/secrets/proxy_ca; \
    fi; \
    npm ci

What it does not do

• It does not make the platform's limits go away: no open ports or previews, and gh pr and gh issue fail (GitHub's GraphQL is blocked; use gh api). gh pr ready fails too; the 403 names a REST route for it (POST /repos/{owner}/{repo}/pulls/{n}/ccr/ready_for_review), not yet verified.
• It does not configure claude.ai for you: the environment is yours to set, following the manual.
• It does not download skills in the cloud; they live in the repo.
• It does not impose a way of testing.
• It does not install plugins, or run the hooks of plugins, from your machine.
• It does not install tools from GitHub releases; the proxy blocks them.
• It does not run Docker inside Docker, and it does not start a Docker daemon in local sessions (the hook exits when CLAUDE_CODE_REMOTE is not true).
• It does not keep secrets safe: environment variables of a cloud environment are readable by anyone who uses it.
• It does not run your setup steps on a resumed session; only a new session does.
• setup runs code fetched from npm as root. The version is pinned in the repo and the relaunch uses exactly that version.

Releasing

For maintainers. Releases are published by .github/workflows/publish.yml when a GitHub release is published; the workflow fails if the release tag, without its leading v, differs from the version in package.json.

The first publish of a new package cannot use npm trusted publishing, because trusted publishing is configured on a package that already exists. Publish the first version by hand:

1. Either run npm ci && npm run build && npm publish --provenance=false from a machine logged in to npm (npm login) with publish rights on the agent-cloud-kit package (provenance needs a CI, and package.json asks for it), or run the workflow once with an NPM_TOKEN secret (NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} on the publish step).
2. On npmjs.com, open the package settings and add a trusted publisher: this GitHub repository and the publish.yml workflow.
3. Remove the NPM_TOKEN secret if you created one. From then on, bump version in package.json, update CHANGELOG.md, and publish a GitHub release tagged v<version>. A version with a prerelease suffix (1.0.0-rc.1) is published under the next tag once a stable version is latest; before that it also becomes latest, so tools that read latest (agent-kitchen) see it. Mark its GitHub release as a pre-release.

License

MIT