Claude Code on Gravix Layer

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 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

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. It extends the Gravix base image and installs Claude Code via Anthropic’s official installer. Throughout these guides, set:

export GRAVIXLAYER_CLAUDE_TEMPLATE="agent-claude"   # your template name

See 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	Identity secret, network allowlist, first interactive + headless run (fixes `ETIMEDOUT` to Anthropic)
Headless automation	`-p`, permission bypass, JSON / stream-json, resume sessions
Repos & git workflows	Clone, `CLAUDE.md`, implement changes, inspect diffs, push
Long-running & parallel agents	Multi-runtime “agent view”, pause/resume, scheduled routines on Gravix
Custom templates & MCP	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
Anthropic API key (ANTHROPIC_API_KEY) with Claude Code access
Python 3.10+ with pip install gravixlayer, or the Gravix 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 when the agent handles untrusted input or secrets.

If claude prints Failed to connect to api.anthropic.com: ETIMEDOUT, the runtime has no working egress to Anthropic. Start with Get started — that is almost always a missing network policy, not a Claude install problem.

​Why Gravix Layer for Claude Code?

​Architecture

​Template

​What you can do

​Claude Code features → Gravix primitives

​Prerequisites (all guides)

​Safety model

Why Gravix Layer for Claude Code?

Architecture

Template

What you can do

Claude Code features → Gravix primitives

Prerequisites (all guides)

Safety model