Share feedback
Answers are generated based on the documentation.

Configure Claude Code

Table of contents
Availability: Experimental
Requires: Docker Desktop 4.58 or later

This guide covers authentication, configuration files, and common options for running Claude Code in a sandboxed environment.

Quick start

To create a sandbox and run Claude Code for a project directory:

$ docker sandbox run claude ~/my-project

Pass a prompt directly

Start Claude with a specific prompt:

$ docker sandbox run <sandbox-name> -- "Add error handling to the login function"

Or:

$ docker sandbox run <sandbox-name> -- "$(cat prompt.txt)"

This starts Claude and immediately processes the prompt.

Authentication

Claude Code requires an Anthropic API key. You can authenticate using an environment variable (recommended) or through interactive login.

The recommended approach is to set the ANTHROPIC_API_KEY environment variable in your shell configuration file.

Docker Sandboxes use a daemon process that doesn't inherit environment variables from your current shell session. To make your API key available to sandboxes, set it globally in your shell configuration file.

Add the API key to your shell configuration file:

~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx

Apply the changes:

  1. Source your shell configuration: source ~/.bashrc (or ~/.zshrc)
  2. Restart Docker Desktop so the daemon picks up the new environment variable
  3. Create and run your sandbox:
$ docker sandbox create claude ~/project
$ docker sandbox run <sandbox-name>

The sandbox detects the environment variable and uses it automatically.

Interactive authentication

If no credentials are found, Claude Code prompts you to authenticate interactively when it starts. You can also trigger the login flow manually using the /login command within Claude Code.

When using interactive authentication:

  • You'll need to authenticate for each workspace/sandbox separately
  • If the sandbox is removed or destroyed, you'll need to authenticate again when you recreate it
  • Authentication sessions aren't persisted outside the sandbox

To avoid repeated authentication, use the ANTHROPIC_API_KEY environment variable method described above.

Configuration

Claude Code can be configured through CLI options. Any arguments you pass after the sandbox name and a -- separator are passed directly to Claude Code.

Pass options after the sandbox name:

$ docker sandbox run <sandbox-name> -- [claude-options]

For example:

$ docker sandbox run <sandbox-name> -- --continue

See the Claude Code CLI reference for available options.

Base image

The Claude Code sandbox template is a container image that runs inside the sandbox VM. It includes:

  • Ubuntu-based environment with Claude Code
  • Development tools: Docker CLI, GitHub CLI, Node.js, Go, Python 3, Git, ripgrep, jq
  • Non-root agent user with sudo access
  • Private Docker daemon for running additional containers

Claude launches with --dangerously-skip-permissions by default in sandboxes.

You can build custom templates based on docker/sandbox-templates:claude-code. See Custom templates for details.

Next steps