claustro

claustro init

Mon, 01 Jan 0001 00:00:00 +0000

claustro init#

Initialize a new claustro project with an interactive setup wizard.

Usage#

claustro init [flags]

Flags#

Flag	Description	Default
`--project`	Project name	directory basename
`--languages`	Comma-separated: go,rust,python	all enabled
`--tools`	Comma-separated: dev,build	all enabled
`--mcp`	Comma-separated: filesystem,memory,fetch	all enabled
`--cpus`	CPU limit	4
`--memory`	Memory limit	8G
`--firewall`	Enable egress firewall	false
`--readonly`	Mount source read-only	false
`-y, --yes`	Accept all defaults	false

Examples#

claustro init
claustro init -y
claustro init --languages go,python --cpus 8 --memory 16G

claustro.yaml

Mon, 01 Jan 0001 00:00:00 +0000

claustro.yaml Reference#

Complete reference for the claustro configuration file.

Top-level fields#

Field	Type	Description
`project`	string	Project name (default: directory basename)
`image`	string or mapping	Custom image name, or image build config
`defaults`	mapping	Default settings for all sandboxes
`sandboxes`	mapping	Named sandbox definitions
`firewall`	mapping	Egress firewall configuration
`mcp`	mapping	MCP server configuration
`git`	mapping	Git integration settings

image#

When a string, uses that image directly. When a mapping, configures the built image.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

Homebrew (macOS / Linux)#

brew tap uniforgeai/tap
brew install claustro

Binary Download#

Download the latest release from GitHub Releases.

Available platforms:

linux/amd64
linux/arm64
darwin/amd64 (Intel Mac)
darwin/arm64 (Apple Silicon)

From Source#

go install github.com/uniforgeai/claustro/cmd/claustro@latest

Prerequisites#

Docker Engine or Docker Desktop must be installed and running
Run claustro doctor to verify your environment

Monorepo Setup

Mon, 01 Jan 0001 00:00:00 +0000

Monorepo Setup#

Run multiple sandboxes targeting different parts of a monorepo.

Named sandboxes#

sandboxes:
 api:
 workdir: ./services/api
 mounts:
 - ./libs:/workspace/libs:ro
 - ./proto:/workspace/proto:ro
 env:
 DATABASE_URL: postgresql://localhost:5432/dev

 web:
 workdir: ./packages/frontend
 env:
 API_URL: http://localhost:3000

Running#

claustro up --name api
claustro up --name web
claustro claude api
claustro claude web
claustro ls

claustro up

Mon, 01 Jan 0001 00:00:00 +0000

claustro up#

Create and start a sandbox container.

Usage#

claustro up [flags]

Flags#

Flag	Description	Default
`--name`	Sandbox name	auto-generated
`--workdir`	Working directory	project root
`--mount`	Additional bind mount (repeatable)	none
`--env`	Environment variable KEY=VALUE (repeatable)	none
`--readonly`	Mount source read-only	false
`--firewall`	Enable egress firewall	false
`--isolated-state`	Use Docker volume for ~/.claude	false

Examples#

claustro up
claustro up --name api --workdir ./services/api
claustro up --mount ./libs:/workspace/libs:ro --firewall

Egress Firewall

Mon, 01 Jan 0001 00:00:00 +0000

Egress Firewall#

Restrict outbound network access from sandboxes.

Enable#

claustro up --firewall

Or in claustro.yaml:

firewall:
 enabled: true
 allow:
 - custom-registry.company.com
 - api.openai.com

Default whitelist#

When enabled, the following domains are always allowed:

api.anthropic.com — Anthropic API
registry.npmjs.org — npm
pypi.org — Python packages
github.com — Git operations
archive.ubuntu.com, security.ubuntu.com — System updates

Docker internal networks (172.16.0.0/12, 192.168.0.0/16, 10.0.0.0/8) are always allowed for compose-sibling services.

Environment Variables

Mon, 01 Jan 0001 00:00:00 +0000

Environment Variables#

Host environment#

Variable	Description
`ANTHROPIC_API_KEY`	Forwarded to sandbox for Claude Code auth
`DOCKER_HOST`	Docker daemon connection (if non-default)

Sandbox environment#

Variable	Description
`HOME`	`/home/sandbox`
`PATH`	Includes Go, Rust, npm, pip paths

Custom variables#

Pass via CLI:

claustro up --env DATABASE_URL=postgresql://localhost:5432/dev

Or in claustro.yaml:

sandboxes:
 api:
 env:
 DATABASE_URL: postgresql://localhost:5432/dev

Or via .env file in the project root.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Quick Start#

1. Initialize your project#

cd ~/projects/my-app
claustro init

This walks you through a setup wizard and creates claustro.yaml. Use claustro init -y to accept all defaults.

2. Start a sandbox#

claustro up

This builds the Docker image (first run only) and starts a sandbox container with your source code mounted at /workspace.

3. Launch Claude Code#

claustro claude

Claude Code starts inside the sandbox with --dangerously-skip-permissions — safe because it’s in a disposable container.

claustro burn

Mon, 01 Jan 0001 00:00:00 +0000

claustro burn#

Stop and remove a sandbox container. Preserves the image and cache volumes.

Usage#

claustro burn [name] [flags]

Flags#

Flag	Description
`--name`	Sandbox name
`--all`	Burn all sandboxes for the current project

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

claustro uses a claustro.yaml file in your project root. Generate one with claustro init or create it manually.

Minimal example#

project: my-app

Full example#

project: my-app

image:
 languages:
 node: true
 go: true
 rust: false
 python: true
 tools:
 dev: true
 build: true
 mcp_servers:
 filesystem: true
 memory: true
 fetch: true

defaults:
 readonly: false
 resources:
 cpus: "4"
 memory: 8G

sandboxes:
 api:
 workdir: ./services/api
 mounts:
 - ./libs:/workspace/libs:ro
 env:
 DATABASE_URL: postgresql://localhost:5432/dev

firewall:
 enabled: false
 allow:
 - custom-registry.company.com

git:
 forward_agent: true
 mount_gitconfig: true
 mount_gh_config: true
 mount_ssh_dir: false

See claustro.yaml Reference for the full schema.

MCP Servers

Mon, 01 Jan 0001 00:00:00 +0000

MCP Servers#

claustro supports stdio-based and SSE-based MCP servers.

Pre-installed (stdio)#

The default image includes:

filesystem — file system access within /workspace
memory — persistent memory for Claude
fetch — HTTP fetching capability

Toggle in claustro.yaml:

image:
 mcp_servers:
 filesystem: true
 memory: true
 fetch: false

Project MCP config#

Place a .mcp.json in your project root. It will be merged with image defaults (project config wins).

SSE sibling containers#

mcp:
 sse:
 postgres:
 image: crystaldba/postgres-mcp-server:latest
 port: 8000
 env:
 DATABASE_URI: postgresql://postgres:postgres@db:5432/devdb

SSE servers run as sibling containers on the same Docker network.

claustro shell

Mon, 01 Jan 0001 00:00:00 +0000

claustro shell#

Open an interactive shell (zsh) inside a running sandbox.

Usage#

claustro shell [name] [flags]

Flags#

Flag	Description
`--name`	Sandbox name

Custom Image

Mon, 01 Jan 0001 00:00:00 +0000

Custom Image Configuration#

Language selection#

Choose which language runtimes to include. Node.js is always installed (required for Claude Code).

image:
 languages:
 node: true
 go: true
 rust: false
 python: true

Tool groups#

image:
 tools:
 dev: true
 build: true

Extra Dockerfile steps#

image:
 extra:
 - run: apt-get update && apt-get install -y ffmpeg
 - run: pip install black ruff

Using a completely custom image#

image: my-registry/my-image:latest

The custom image must have Claude Code pre-installed.

claustro claude

Mon, 01 Jan 0001 00:00:00 +0000

claustro claude#

Launch Claude Code inside a sandbox. Automatically starts a sandbox if none is running.

Usage#

claustro claude [name] [flags] [-- claude-args...]

Flags#

Flag	Description
`--name`	Sandbox name

Examples#

claustro claude
claustro claude api
claustro claude -- --model opus

claustro config

Mon, 01 Jan 0001 00:00:00 +0000

claustro config#

View and modify claustro configuration.

Interactive Subcommands#

claustro config languages # Configure image languages
claustro config tools # Configure tool groups
claustro config mcp # Configure MCP servers
claustro config defaults # Configure resource defaults
claustro config firewall # Configure firewall settings
claustro config git # Configure git integration

Get/Set#

claustro config get <path>
claustro config set <path> <value>

Examples#

claustro config get image.languages.go
claustro config set defaults.resources.cpus 8
claustro config set image.languages.rust true

claustro validate

Mon, 01 Jan 0001 00:00:00 +0000

claustro validate#

Validate the claustro.yaml configuration file.

Usage#

claustro validate

Exit Codes#

Code	Meaning
0	Valid (warnings OK)
1	Errors found

claustro doctor

Mon, 01 Jan 0001 00:00:00 +0000

claustro doctor#

Check host environment health. Validates Docker, git, SSH, clipboard, and configuration.

Usage#

claustro doctor

claustro exec

Mon, 01 Jan 0001 00:00:00 +0000

claustro exec#

Run a command inside a running sandbox.

Usage#

claustro exec [name] -- <command> [args...]

Flags#

Flag	Description
`--name`	Sandbox name

Examples#

claustro exec -- go test ./...
claustro exec api -- npm run build

claustro ls

Mon, 01 Jan 0001 00:00:00 +0000

claustro ls#

List sandboxes for the current project.

Usage#

claustro ls [flags]

Flags#

Flag	Description
`--all`	List sandboxes across all projects

claustro nuke

Mon, 01 Jan 0001 00:00:00 +0000

claustro nuke#

Remove a sandbox and its cache volumes. Preserves the image.

Usage#

claustro nuke [name] [flags]

Flags#

Flag	Description
`--all`	Nuke all sandboxes for the current project

claustro rebuild

Mon, 01 Jan 0001 00:00:00 +0000

claustro rebuild#

Rebuild the Docker image from scratch.

Usage#

claustro rebuild [flags]

Flags#

Flag	Description	Default
`--restart`	Restart running sandboxes after rebuild	false

claustro status

Mon, 01 Jan 0001 00:00:00 +0000

claustro status#

Show sandbox details including state, uptime, resource usage, and mounted paths.

Usage#

claustro status [name] [flags]

Flags#

Flag	Description
`--name`	Sandbox name

claustro logs

Mon, 01 Jan 0001 00:00:00 +0000

claustro logs#

Display container logs.

Usage#

claustro logs [name] [flags]

Flags#

Flag	Description	Default
`--name`	Sandbox name
`-f, --follow`	Follow log output	false
`--tail`	Number of lines to show	100