Claude CodeLesson

Cloud sessions

A session on your laptop has your tools, your sign-ins and your settings. A cloud session starts on a fresh machine with what the repository holds plus what its cloud environment sets. Whatever a project needs in every session must therefore be committed or set there, and the cloud's own network limits what the session can reach.

Know cloud sessions already? Skip to In Terrarium.

Outside the box · General

The concept

A cloud session is a Claude Code session that runs on a virtual machine Anthropic manages, started from claude.ai/code, the Claude app, the Desktop app or claude --cloud. It clones your repository fresh. In a session with one repository, committed files arrive: CLAUDE.md, .claude/rules/, .claude/skills/, .mcp.json and .claude/settings.json. Nothing from your own machine does, such as ~/.claude/settings.json, .claude/settings.local.json or a server you added only for yourself, and of an organization's managed settings only the server-managed ones can reach it. Claude Code permissions shows how the settings that do arrive decide which tool calls run unasked. Each session runs in a cloud environment, which sets its network access, its environment variables and a setup script. GitHub goes through a proxy that holds your credentials outside the machine, and that proxy refuses GitHub's GraphQL API.

Full referenceClaude Code docs: Use Claude Code in the cloud

Looking inside

In Terrarium

Every runs as a cloud session, and so does any session started from claude.ai. Everything a Terrarium session needs is in the repo. A SessionStart hook installs dependencies and fetches full git history when the clone is shallow, as Claude Code hooks shows.

The committed .claude/settings.json holds env variables, a short permissions.allow list and the hooks. Which of those a cloud session uses depends on how it starts. A session with one repository reads the file. docs/agents/environment-caveats.md records that a multi-repository cloud session reads only enabledPlugins and extraKnownMarketplaces from it, which the settings docs say of a session in an Anthropic-hosted environment, and that an untrusted workspace drops permissions.allow before matching any rule; Claude Code permissions explains the trust rule behind it. Terrarium's guards are hooks, and docs/agents/guards.md records them firing in a cloud session, a dispatched subagent's calls included, when probed.

The cloud also fences what a session can reach. A few of the limits Terrarium has met: the token can't push .github/workflows/, a change there goes to a person as a , and Merge gate shows where the 's CI steps live instead; the proxy refuses writes to repository settings; and some docs sites are blocked. For the first, scripts/hooks/workflow-edit-guard.ts, a PreToolUse hook, denies an edit or a write-shaped command aimed at .github/workflows/, and only when a variable the cloud sets is present:

scripts/hooks/workflow-edit-guard.ts ↗71–152as of 1 Nov 2026

71/** The variable the provenance guards also read; only a cloud session sets it. */
72export function isCloudSession(env: NodeJS.ProcessEnv = process.env): boolean {
73  return Boolean(env.CLAUDE_CODE_REMOTE_SESSION_ID)
74}
⋯// …
143export function main(): void {
144  if (!isCloudSession()) return
⋯  // …
152}

docs/agents/environment-caveats.md holds the current list.

Why it's built this way

Stop a workflow edit before it is committed. A cloud session's token can't push .github/workflows/, and the refusal covers every commit in the push, so one workflow edit strands the work beside it. So the guard denies the edit at the tool call, before any commit exists. The cost: it matches command text, so a path held in a variable slips past to the refused push. scripts/hooks/workflow-edit-guard.ts.

What to watch for

A 403 is often the environment. A GraphQL gh command, a blocked docs site or a refused settings call fails the same way every time. Read the caveats before you diagnose it as a bug in your change.
Your own settings never reach the cloud. A hook or permission you set in your own ~/.claude/settings.json never reaches a cloud session. Put what every session needs in the project file; a session with several repositories reads none of that file's hooks, so give it a setup script on the environment instead.

Try it in your project

Commit a SessionStart hook to your project's .claude/settings.json that installs your dependencies. Start a cloud session on the repository and check that the install ran before Claude's first answer.

Where next

Last updated 1 Nov 2026 · Latest source on GitHub ↗