Get started with Claude Code

This page gets you from zero to a working Claude Code sandbox:

Set API keys
Create an Identity provider + network allowlist
Create a runtime from the platform claude template and smoke-test with claude -p
Open an interactive shell

1. Environment

export GRAVIXLAYER_API_KEY="your-gravixlayer-api-key"
export ANTHROPIC_API_KEY="sk-ant-..."

pip install gravixlayer
npm install gravixlayer
# or: curl -fsSL https://cli.gravixlayer.ai/install | sh

Use the platform template name claude (Claude Code is already installed). Do not omit --template — the CLI default is base-small, which does not include claude. Sandboxes block outbound traffic by default. Without a network policy that allows api.anthropic.com:443, Claude cannot reach Anthropic.

2. Create sandbox and smoke-test

The examples below create a provider, an allowlist, a runtime on claude, run a short headless prompt, then print IDs you can reuse. They leave the runtime running so you can open a shell next.

import os
import uuid

from gravixlayer import GravixLayer

ANTHROPIC_API_KEY = os.environ["ANTHROPIC_API_KEY"]

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"

provider = client.identity.providers.create(
    name=f"anthropic-claude-{uuid.uuid4().hex[:8]}",
    provider_type="api_key",
    secrets=[{"key": "ANTHROPIC_API_KEY", "value": ANTHROPIC_API_KEY}],
)

policy = client.network_policies.create(
    name=f"claude-anthropic-{uuid.uuid4().hex[:8]}",
    egress_mode="allowlist",
    description="Claude Code → Anthropic API",
    rules=[
        {
            "destination": "api.anthropic.com",
            "port": 443,
            "protocol": "tcp",
            "description": "Anthropic Messages API",
        },
    ],
)

# env_vars: needed for interactive shell / SSH (Identity injects for run_cmd only)
sandbox = client.runtime.create(
    template="claude",
    providers=[provider.id],
    network_policy_ids=[policy.id],
    env_vars={"ANTHROPIC_API_KEY": ANTHROPIC_API_KEY},
    timeout=3600,
)

result = sandbox.run_cmd(
    command="claude",
    args=[
        "--dangerously-skip-permissions",
        "-p",
        "Reply with exactly: pong",
        "--output-format",
        "text",
    ],
    timeout=300,
)
print(result.stdout)
print("exit_code:", result.exit_code)

# Reuse these in later guides
print(f'export ANTHROPIC_PROVIDER_ID="{provider.id}"')
print(f'export CLAUDE_NETWORK_POLICY_ID="{policy.id}"')
print(f'export RT="{sandbox.runtime_id}"')

# When finished: sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const ANTHROPIC_API_KEY = process.env['ANTHROPIC_API_KEY']!;

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"

const provider = await client.identity.providers.create(`anthropic-claude-${Date.now()}`, {
  providerType: 'api_key',
  secrets: [{ key: 'ANTHROPIC_API_KEY', value: ANTHROPIC_API_KEY }],
});

const policy = await client.networkPolicies.create(`claude-anthropic-${Date.now()}`, {
  egressMode: 'allowlist',
  description: 'Claude Code → Anthropic API',
  rules: [
    {
      destination: 'api.anthropic.com',
      port: 443,
      protocol: 'tcp',
      description: 'Anthropic Messages API',
    },
  ],
});

// envVars: needed for interactive shell / SSH (Identity injects for runCmd only)
const sandbox = await client.runtime.create({
  template: 'claude',
  providers: [provider.id],
  networkPolicyIds: [policy.id],
  envVars: { ANTHROPIC_API_KEY },
  timeout: 3600,
});

const result = await sandbox.runCmd('claude', {
  args: [
    '--dangerously-skip-permissions',
    '-p',
    'Reply with exactly: pong',
    '--output-format',
    'text',
  ],
  timeout: 300,
});
console.log(result.stdout);
console.log('exit_code:', result.exitCode);

console.log(`export ANTHROPIC_PROVIDER_ID="${provider.id}"`);
console.log(`export CLAUDE_NETWORK_POLICY_ID="${policy.id}"`);
console.log(`export RT="${sandbox.runtimeId}"`);

// When finished: await sandbox.kill()

PROVIDER_ID=$(gravixlayer provider create \
  "anthropic-claude-$(openssl rand -hex 4)" \
  --type api_key \
  --secret "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" \
  --output json | jq -r '.id')

POLICY_ID=$(gravixlayer network-policy create \
  "claude-anthropic-$(openssl rand -hex 4)" \
  --egress-mode allowlist \
  --description "Claude Code → Anthropic API" \
  --output json | jq -r '.id')

gravixlayer network-policy add-rule "$POLICY_ID" \
  --destination api.anthropic.com \
  --port 443 \
  --protocol tcp \
  --description "Anthropic Messages API"

RT=$(gravixlayer runtime create \
  --template claude \
  --provider "$PROVIDER_ID" \
  --network-policy "$POLICY_ID" \
  --env "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" \
  --timeout 3600 \
  --wait \
  --output json | jq -r '.runtime_id')

gravixlayer runtime exec "$RT" --timeout 300 -- \
  claude --dangerously-skip-permissions \
  -p 'Reply with exactly: pong' \
  --output-format text

echo "export ANTHROPIC_PROVIDER_ID=$PROVIDER_ID"
echo "export CLAUDE_NETWORK_POLICY_ID=$POLICY_ID"
echo "export RT=$RT"

API="https://api.gravixlayer.ai/v1"
AUTH=(-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json")

PROVIDER_ID=$(curl -sS -X POST "$API/identity/providers" "${AUTH[@]}" \
  -d "{
    \"name\": \"anthropic-claude-$(openssl rand -hex 4)\",
    \"provider_type\": \"api_key\",
    \"secrets\": [{\"key\": \"ANTHROPIC_API_KEY\", \"value\": \"$ANTHROPIC_API_KEY\"}]
  }" | jq -r '.provider.id')

POLICY_ID=$(curl -sS -X POST "$API/network-policies" "${AUTH[@]}" \
  -d "{
    \"name\": \"claude-anthropic-$(openssl rand -hex 4)\",
    \"egress_mode\": \"allowlist\",
    \"description\": \"Claude Code → Anthropic API\"
  }" | jq -r '.policy.id')

curl -sS -X POST "$API/network-policies/$POLICY_ID/rules" "${AUTH[@]}" \
  -d '{
    "destination": "api.anthropic.com",
    "port": 443,
    "protocol": "tcp",
    "description": "Anthropic Messages API"
  }' >/dev/null

RT=$(curl -sS -X POST "$API/agents/runtime" "${AUTH[@]}" \
  -d "{
    \"template\": \"claude\",
    \"cloud\": \"aws\",
    \"region\": \"us-east-1\",
    \"timeout\": 3600,
    \"providers\": [\"$PROVIDER_ID\"],
    \"network_policy_ids\": [\"$POLICY_ID\"],
    \"env_vars\": {\"ANTHROPIC_API_KEY\": \"$ANTHROPIC_API_KEY\"}
  }" | jq -r '.runtime_id')

for i in $(seq 1 60); do
  STATUS=$(curl -sS "$API/agents/runtime/$RT" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" | jq -r '.status')
  [ "$STATUS" = "running" ] && break
  sleep 2
done

# timeout is milliseconds on the HTTP API
curl -sS -X POST "$API/agents/runtime/$RT/commands/run" "${AUTH[@]}" \
  -d '{
    "command": "claude",
    "args": [
      "--dangerously-skip-permissions",
      "-p", "Reply with exactly: pong",
      "--output-format", "text"
    ],
    "timeout": 300000
  }' | jq .

echo "export ANTHROPIC_PROVIDER_ID=$PROVIDER_ID"
echo "export CLAUDE_NETWORK_POLICY_ID=$POLICY_ID"
echo "export RT=$RT"

Identity secrets are injected for run_cmd / run_code. Interactive runtime shell / SSH does not get them automatically — that is why we also pass env_vars at create time.

3. Interactive shell

gravixlayer runtime shell "$RT"

Inside the sandbox:

claude --version
claude

You should get the Claude Code TUI. When you are done:

gravixlayer runtime kill "$RT" -y

Optional allowlist hosts

Destination	Why
`api.anthropic.com`	Model API (required)
`github.com`	HTTPS git
`registry.npmjs.org`	`npm install`
`pypi.org`, `files.pythonhosted.org`	`pip` / `uv`

For a quick experiment you can use --egress-mode allow_all, then tighten. See Network policies.

Troubleshooting

Symptom	Likely cause
Cannot reach Anthropic	Missing network policy or `api.anthropic.com:443`
Auth / invalid API key	Key missing in that session (shell vs `run_cmd`)
`claude: command not found`	Runtime was not created with `--template claude` (CLI defaults to `base-small`)
Permission bypass refused	Template missing `IS_SANDBOX=1`, or exec not running as `agent`

Guides

Get started with Claude Code

1. Environment

2. Create sandbox and smoke-test

3. Interactive shell

Optional allowlist hosts

Troubleshooting

Next

​1. Environment

​2. Create sandbox and smoke-test

​3. Interactive shell

​Optional allowlist hosts

​Troubleshooting

​Next

1. Environment

2. Create sandbox and smoke-test

3. Interactive shell

Optional allowlist hosts

Troubleshooting

Next