> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code on Gravix Layer

> Run Anthropic Claude Code inside isolated Gravix Layer sandboxes — interactive shells, headless agents, git workflows, and long-running automations.

[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic’s agentic coding CLI. Gravix Layer gives it a **dedicated microVM**: filesystem, terminal, git, and outbound network you control — without running the agent on your laptop.

This guide series shows how to use Claude Code as:

* A **day-to-day coding sandbox** (interactive `claude` in a runtime shell)
* A **headless worker** you drive from Python or the Gravix CLI (`-p`, JSON, session resume)
* A **platform building block** for repo work, parallel agents, and scheduled jobs

## Why Gravix Layer for Claude Code?

| Need        | On your machine                                   | On Gravix Layer                                                                                                   |
| ----------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Isolation   | Agent can touch local files & credentials         | Runs in a microVM; host stays untouched                                                                           |
| Permissions | `--dangerously-skip-permissions` is risky locally | Safe inside the sandbox (`IS_SANDBOX` is set on the Claude template)                                              |
| Network     | Wide open by default                              | **Deny-by-default** egress — you attach an allowlist                                                              |
| Secrets     | Easy to leak into prompts                         | [Identity providers](/documentation/agentruntime/getting-started/identity-providers) inject env vars at exec time |
| Scale       | One laptop, one session                           | Many runtimes in parallel, pause/resume, kill when done                                                           |

Claude Code still talks to Anthropic’s API. Gravix Layer is the **execution environment** — not a replacement for Anthropic auth or model access.

## Architecture

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Your app / CLI / CI
        │
        ▼
 Gravix Layer API  ──►  Runtime (microVM)
                           │
                           ├─ claude CLI (agent-claude template)
                           ├─ /workspace filesystem
                           ├─ git, python, node toolchain
                           └─ egress via network policy
                                    │
                                    ▼
                           api.anthropic.com (and hosts you allow)
```

## Template

Build (or use) a template from [`agent-claude.Dockerfile`](https://github.com/gravixlayer/gravixlayer-python/blob/main/examples/templates/dockerfiles/agent-claude.Dockerfile). It extends the Gravix base image and installs Claude Code via Anthropic’s official installer.

Throughout these guides, set:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export GRAVIXLAYER_CLAUDE_TEMPLATE="agent-claude"   # your template name
```

See [Templates](/documentation/agentruntime/templates) for base sizes and how to build custom images. Prefer **≥ 8 GB disk** so the Claude CLI and toolchain fit comfortably.

## What you can do

| Guide                                                                     | What you’ll learn                                                                                     |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [Get started](/guides/claude-code/get-started)                            | Identity secret, network allowlist, first interactive + headless run (fixes `ETIMEDOUT` to Anthropic) |
| [Headless automation](/guides/claude-code/headless)                       | `-p`, permission bypass, JSON / stream-json, resume sessions                                          |
| [Repos & git workflows](/guides/claude-code/repo-workflows)               | Clone, `CLAUDE.md`, implement changes, inspect diffs, push                                            |
| [Long-running & parallel agents](/guides/claude-code/long-running-agents) | Multi-runtime “agent view”, pause/resume, scheduled routines on Gravix                                |
| [Custom templates & MCP](/guides/claude-code/custom-templates)            | Extend the Claude image, bake skills/config, wire MCP tools                                           |

## Claude Code features → Gravix primitives

Anthropic continues to ship product features (dynamic workflows, agent view, routines, Dispatch / computer use). On Gravix Layer you map them like this:

| Claude Code capability          | How it shows up on Gravix                                                               |
| ------------------------------- | --------------------------------------------------------------------------------------- |
| Interactive TUI                 | `gravixlayer runtime shell` or SSH into a running runtime                               |
| Headless `-p`                   | `runtime.run_cmd(...)` / `gravixlayer runtime exec`                                     |
| Session resume (`--resume`)     | Same runtime filesystem keeps Claude session state under `/workspace`                   |
| Dynamic / multi-agent workflows | One larger runtime, or fan out across **many Gravix runtimes**                          |
| Agent view (many sessions)      | Track multiple `runtime_id`s; shell into the one that needs you                         |
| Routines (schedule / webhook)   | Your orchestrator (cron, GitHub Action, API) creates a runtime and runs `claude -p ...` |
| Computer use / Dispatch         | Prefer sandbox + CLI tools over host desktop control; Gravix isolates the agent         |

## Prerequisites (all guides)

* [Gravix Layer API key](/documentation/agentruntime/getting-started/api-keys)
* Anthropic API key (`ANTHROPIC_API_KEY`) with Claude Code access
* Python 3.10+ with `pip install gravixlayer`, **or** the [Gravix CLI](https://github.com/gravixlayer/gravixlayer-cli)
* A built Claude template (`GRAVIXLAYER_CLAUDE_TEMPLATE`)

Every runnable example in this series is written against:

| Surface                                    | Used for                                                                                     |
| ------------------------------------------ | -------------------------------------------------------------------------------------------- |
| Python SDK (`gravixlayer`)                 | `client.runtime`, `client.identity.providers`, `client.network_policies`, `client.templates` |
| CLI (`gravixlayer`)                        | `runtime create/exec/shell/kill/pause/resume`, `provider`, `network-policy`                  |
| REST (`https://api.gravixlayer.ai/v1/...`) | Same operations via `curl` (agents runtime under `/v1/agents/runtime`)                       |

## Safety model

`--dangerously-skip-permissions` auto-approves tool calls **inside the sandbox**. That is intentional for headless agents. It does **not** protect outbound network — Claude can still call any host you allow. Keep egress on an [allowlist](/documentation/agentruntime/getting-started/network-policies) when the agent handles untrusted input or secrets.

<Tip>
  If `claude` prints `Failed to connect to api.anthropic.com: ETIMEDOUT`, the runtime has no working egress to Anthropic. Start with [Get started](/guides/claude-code/get-started) — that is almost always a missing network policy, not a Claude install problem.
</Tip>