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 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.
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.
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"
}

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

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

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