Search learning paths, guides, and videos.

    Guide

    Run an agent safely in a Docker Sandbox

    • Beginner
    • 15 min
    • Published
    • Verified

    What you'll learn

    • Launch Codex in a named sandbox
    • Confirm which workspace is shared with the agent
    • Review the active network policy

    The terminals below are simulated. Nothing runs on your machine, and each one starts from the state the guide has reached at that point.

    You’ll launch Codex in a named sandbox, confirm which workspace is shared with it, and review the active network policy — trying each command in the page as you read.

    The commands below assume sbx is installed, that you are signed in, and that you selected the Balanced network policy during setup. They also assume Codex can sign in: store your OpenAI credential first, with sbx secret set openai --oauth if you sign in to Codex with ChatGPT, or sbx secret set openai to paste an API key. Without one, sbx run stops to ask whether to sign in now or start Codex logged out.

    Launch the agent

    From a project directory, launch Codex in a sandbox named learn-agent:

    Terminal

    sbx run --name learn-agent codex
    SANDBOX
      Name:       learn-agent
      Agent:      codex
      Workspace:  ~/my-project (rw)
      Skills:     0 entries · linked, read-only
        Source:   ~/.local/state/sandboxes/sandboxes/agent-skills
        Target:   /home/agent/.agents/skills
      Image:      docker/sandbox-templates:codex-docker
      CPU:        4
      Memory:     4g
    
    IMAGE
      ✓ image — ready
    
      ✓ Created sandbox learn-agent
    
      ○ codex — starting in sandbox learn-agent…
          workspace /home/moby/my-project

    sbx run creates the sandbox when needed, then starts Codex and attaches your terminal to it. The Workspace line shows the one host directory the agent gets, mounted read-write (rw). The first run takes longer while sbx pulls the Codex image; later runs check it for updates and reuse the layers already on your machine.

    Review the sandbox boundary

    From another terminal, list the running sandboxes, then inspect the network rules that apply to them:

    Terminal

    sbx ls
    SANDBOX       AGENT   STATUS      PORTS   WORKSPACE               CREATED
    learn-agent   codex   ● running           /home/moby/my-project   1m
    sbx policy ls
    POLICY                                 SOURCE   APPLIES TO            SUMMARY
    d5e9ca3a-572c-430a-b4b4-b02d47a8b03a   kit      sandbox:learn-agent   network: 15 allow
    local-policy                           local    all                   network: 194 allow; filesystem read: 1 allow; filesystem write: 1 allow

    The WORKSPACE column identifies the host directory shared with the agent. The sandbox’s remaining filesystem and its Docker daemon stay inside the microVM.

    Sandbox networking is deny-by-default: a sandbox reaches only the hosts a policy allows. Two policies apply to learn-agent:

    • local-policy applies to every sandbox. It holds the Balanced rules you chose during setup, which allow AI providers and common development services such as package registries.
    • The kit policy applies only to learn-agent. sbx added it for the Codex agent, allowing the OpenAI, GitHub, npm, and Ubuntu package hosts Codex needs. Its name is an ID sbx generates, so yours differs.

    Every other host is blocked.