> For the complete documentation index, see [llms.txt](https://docs.locusai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.locusai.dev/getting-started/sandboxing-setup.md).

# Sandboxing Setup (Docker-First)

Use this guide when you want Locus runs isolated inside Docker sandboxes. The setup is the same whether you use Claude or Codex.

{% hint style="info" %}
Prerequisite: complete [Installation](/getting-started/installation.md) first so `locus`, `gh`, and at least one AI CLI are installed.
{% endhint %}

## Prerequisites

| Requirement                                                             | Why it is required                                             |
| ----------------------------------------------------------------------- | -------------------------------------------------------------- |
| [Docker Desktop](https://www.docker.com/products/docker-desktop/) 4.58+ | Provides the `docker sandbox` runtime Locus uses for isolation |
| Docker daemon running                                                   | Locus cannot create or sync sandboxes if Docker is stopped     |
| Locus initialized in the repo (`locus init`)                            | Creates `.locus/` config and `.sandboxignore` defaults         |

## Platform Caveats

* macOS and Windows: install Docker Desktop 4.58+ and keep Docker Desktop running.
* Linux: sandboxing requires Docker with the `docker sandbox` command available. If your Docker install does not provide it, Locus cannot run sandboxed on that machine.
* CI or headless hosts: use `--sandbox=require` to fail fast when sandbox support is missing.

## Step 1: Verify Docker Availability

Run these commands before enabling sandbox mode:

```bash
docker --version
docker info
docker sandbox ls
```

Expected outcome:

* `docker --version` returns a valid version.
* `docker info` returns daemon details without connection errors.
* `docker sandbox ls` runs without an "unknown command" error.

## Step 2: Initialize Locus in the Repository

```bash
cd /path/to/your-repo
locus init
```

Expected outcome:

* `.locus/config.json` exists.
* `.sandboxignore` exists (generated if missing).

## Step 3: Create a Provider Sandbox

Run `locus sandbox` and select which provider you want to use:

```bash
locus sandbox
```

You will be prompted to choose a provider:

```
Select a provider to create a sandbox for:

  1. claude
  2. codex

Enter choice (1-2):
```

Expected outcome:

* Locus creates a sandbox for the selected provider.
* `sandbox.enabled` is turned on in `.locus/config.json`.

If you use both providers, run `locus sandbox` again and select the other provider.

Check state anytime:

```bash
locus sandbox status
```

## Step 4: Authenticate Inside the Sandbox

Authenticate the provider in its sandbox:

```bash
# If you chose claude
locus sandbox claude

# If you chose codex
locus sandbox codex
```

Expected outcome:

* Provider credentials are stored in the sandbox environment.
* Later `locus run`, `locus exec`, and other AI commands can execute without host credential exposure.

## Step 5: Choose Model, Run, and Verify Isolation

Pick a model and run with required sandboxing:

```bash
# Claude example
locus config set ai.model claude-sonnet-4-6
locus run <issue-number> --sandbox=require
```

Switch to Codex with the same workflow:

```bash
locus config set ai.model gpt-5.3-codex
locus run <issue-number> --sandbox=require
```

Expected outcome:

* You switch providers only by changing `ai.model`.
* The sandboxing layer stays the same (Docker sandbox + workspace sync + `.sandboxignore` enforcement).

## Optional: Custom Sandbox Setup Script

For non-JavaScript projects (Python, Rust, Go, etc.) or projects requiring extra system dependencies, create a `.locus/sandbox-setup.sh` script. Locus runs this script automatically inside each new sandbox after creation.

```bash
#!/bin/sh
# .locus/sandbox-setup.sh — Example for a Python project
apt-get update && apt-get install -y python3 python3-pip
pip install -r requirements.txt
```

For more examples and details, see [Custom Setup with sandbox-setup.sh](/cli-reference/sandbox.md#custom-setup-with-sandbox-setupsh).

## Optional: Customize Shell Environment

If you need custom environment variables, aliases, or `PATH` entries when using `locus sandbox shell`, create a `.locus/sandbox-profile.sh` file:

```bash
#!/bin/sh
# .locus/sandbox-profile.sh — Example shell customization
export DATABASE_URL="postgres://localhost:5432/devdb"
export PATH="/opt/custom-tools/bin:$PATH"
alias t='npm test'
```

This file is sourced automatically when you open an interactive sandbox shell. It does not affect automated AI agent execution.

For more details, see [Shell Environment with sandbox-profile.sh](/cli-reference/sandbox.md#shell-environment-with-sandbox-profilesh).

## Optional: Install Extra Tools Inside Sandbox

If your workflow needs additional CLIs inside provider sandboxes (for example `bun`), install them globally:

```bash
# Install in all configured provider sandboxes
locus sandbox install bun

# Install only in codex sandbox
locus sandbox install bun --provider codex
```

You can then verify or use tools directly in the sandbox:

```bash
locus sandbox exec codex -- bun --version
```

Use interactive access and logs when debugging sandbox behavior:

```bash
# Open shell inside a sandbox
locus sandbox shell codex

# View sandbox logs
locus sandbox logs codex --follow
```

## Unified Interface: Claude and Codex on One Sandboxing Layer

Locus keeps a single command interface across providers:

* Same commands: `locus run`, `locus exec`, `locus review`, `locus iterate`
* Same sandbox control: `locus sandbox`, `locus sandbox status`
* Same safety mode options: default sandboxed behavior, `--sandbox=require`, or explicit `--no-sandbox`

Provider changes do not require a different security setup or different run command structure.

## Troubleshooting

### Startup Failure: Sandbox Cannot Start

Symptoms:

* `Docker sandbox required but not available`
* `Docker is not installed`
* `Docker is not responding`
* `Docker Desktop 4.58+ with sandbox support required`

Fixes:

1. Start Docker Desktop and wait until it is fully initialized.
2. Re-run `docker info` and `docker sandbox ls`.
3. Upgrade Docker Desktop to 4.58+ if `docker sandbox` is unavailable.
4. Use `locus run ... --sandbox=require` during validation so failures are explicit.

### Permission Issue: Docker Access Denied

Symptoms:

* Permission denied on Docker socket or sandbox commands.
* Commands work only with elevated privileges.

Fixes:

1. Confirm your user has permission to access Docker (for Linux, ensure your user is in the Docker group and start a new shell session).
2. Make sure your terminal session matches the user account running Docker Desktop.
3. Re-check with `docker info` before retrying `locus sandbox`.

### Sync Issue: Files Not Appearing as Expected

Symptoms:

* Changes made during a run are not visible where expected.
* Certain files are intentionally missing in sandbox execution.

Fixes:

1. Check `.sandboxignore` for excluded files or directories.
2. Re-run the command; Locus re-syncs workspace content before sandboxed execution.
3. Avoid editing huge generated files continuously during runs; large/high-frequency writes can cause visible sync lag.
4. Verify you are running in the expected repository path (`pwd`) and not a stale worktree.

## Next References

1. [Security & Sandboxing](/workflow-deep-dives/security-sandboxing.md)
2. [locus sandbox](/cli-reference/sandbox.md)
3. [locus run](/cli-reference/run.md)
4. [locus exec](/cli-reference/exec.md)