Sandboxing: cwd, env, and Network

The agent only knows what you let it see

Three knobs scope the agent's blast radius. cwd sets the working directory — Read/Write/Edit/Bash all run from there. env sets the environment variables visible to subprocess tools. Network access can be gated at the OS layer (firewall, VPN) or via your own MCP servers' policies.

Set cwd to the smallest viable directory

If the agent only needs to edit files under /srv/myapp, do not set cwd to /. The model will see paths relative to cwd, and the SDK will refuse paths that escape it (with default settings). Narrow cwd is half the sandbox.

Strip env to minimum

Bash inherits the env you provide. If you forward your full shell environment, the agent has access to every credential variable. Provide only what tools genuinely need: PATH, HOME, plus task-specific keys. Leak protection is mostly env protection.

Principle: Sandboxing is not 'install Docker'. It is choosing what cwd, env, and tool list the agent gets. Each is a minimum viable scope decision.

Code

Tight sandbox options·python

import os

options = ClaudeAgentOptions(
    cwd="/srv/agent-workspace",  # NOT /
    env={
        "PATH": "/usr/local/bin:/usr/bin:/bin",
        "HOME": "/srv/agent-workspace",
        "LANG": "en_US.UTF-8",
        # ONLY the keys this task needs:
        "WEATHER_API_KEY": os.environ["WEATHER_API_KEY"],
    },
    allowed_tools=["Read", "Bash"],
    permission_mode="default",
)

Containerized sandbox for untrusted runs·yaml

# docker-compose.yml — run the agent inside a container with a read-only mount
services:
  agent:
    image: claude-agent:latest
    read_only: true
    tmpfs:
      - /tmp
      - /var/run
    volumes:
      - ./workspace:/workspace
      - ./input:/input:ro
    networks:
      - egress-allowlisted
    environment:
      - PATH=/usr/local/bin:/usr/bin:/bin
      # Inject only task-specific secrets
networks:
  egress-allowlisted:
    driver: bridge
    internal: false
    # outbound rules enforced by external firewall / Calico / similar

Sandboxing: cwd, env, and Network

The agent only knows what you let it see

Set cwd to the smallest viable directory

Strip env to minimum

Code

External links

Exercise

Progress

Comments 0