agentkernel sandbox create

Create a new persistent sandbox. The sandbox remains available until explicitly removed.

Usage

agentkernel sandbox create [OPTIONS] [NAME]

Arguments

Argument	Description
`[NAME]`	Name for the sandbox (alphanumeric, hyphens, underscores). Optional when `--branch` is used.

Options

Option	Description
`--config <FILE>`	Path to agentkernel.toml config file
`--template <NAME>`	Use a built-in or custom template
`--agent <AGENT>`	Agent type: `claude`, `codex`, `gemini`, `opencode`
`--dir <PATH>`	Project directory to mount
`-B, --backend <BACKEND>`	Backend: `docker`, `podman`, `firecracker`, `apple`
`--branch`	Auto-name from git project and branch
`--ttl <DURATION>`	Auto-expire after duration (e.g. `1h`, `30m`, `3d`)
`-p, --publish <PORT>`	Port mapping (e.g. `8080:80`, `3000`, `5353:53/udp`). Repeatable.
`--ssh`	Enable SSH access to the sandbox
`-S, --secret <BINDING>`	Bind a secret to a host via proxy. Repeatable. See Secrets.
`--secret-file <KEY>`	Inject a vault secret as a file. Repeatable. See Secrets.
`--placeholder-secrets`	Use placeholder tokens for `--secret-file` (real values stay on host).

Examples

Basic sandbox

# Create with default settings
agentkernel sandbox create my-sandbox

# Create with specific agent preset
agentkernel sandbox create my-sandbox --agent claude

Using a config file

# Create from config (auto-builds Dockerfile if specified)
agentkernel sandbox create my-project --config agentkernel.toml

# Use example agent configs
agentkernel sandbox create claude-dev --config examples/agents/claude-code/agentkernel.toml

With project directory

# Mount current directory into sandbox
agentkernel sandbox create my-project --config agentkernel.toml --dir .

From a template

# List available templates
agentkernel template list

# Create from built-in template
agentkernel sandbox create my-sandbox --template python
agentkernel sandbox create my-sandbox --template rust-ci
agentkernel sandbox create my-sandbox --template claude-sandbox

Per-branch sandboxes

# Auto-derive name from git project + branch (e.g. "myproject-feature-auth")
agentkernel sandbox create --branch -B docker

# Reuse the same sandbox across sessions for the same branch
agentkernel sandbox create --branch -B docker  # creates or reuses

With TTL (auto-expiry)

# Sandbox expires after 1 hour
agentkernel sandbox create my-sandbox --ttl 1h

# Expires after 3 days
agentkernel sandbox create my-sandbox --ttl 3d

# No expiry (default)
agentkernel sandbox create my-sandbox --ttl 0

Run agentkernel sandbox gc to garbage-collect expired sandboxes.

Port mapping

# Map host port 8080 to container port 80
agentkernel sandbox create web-app -p 8080:80

# Multiple port mappings
agentkernel sandbox create web-app -p 8080:80 -p 3000:3000

# Container port only (host port auto-assigned)
agentkernel sandbox create api -p 3000

# UDP port mapping
agentkernel sandbox create dns -p 5353:53/udp

Ports are also configurable in agentkernel.toml:

[network]
ports = ["8080:80", "3000"]

Specify backend

# Force Docker backend
agentkernel sandbox create my-sandbox -B docker

# Use Firecracker (Linux with KVM)
agentkernel sandbox create my-sandbox -B firecracker

Auto-Build from Dockerfile

When your config specifies a Dockerfile, create automatically builds it:

# agentkernel.toml
[build]
dockerfile = "Dockerfile"

[sandbox]
name = "my-app"

$ agentkernel sandbox create my-app --config agentkernel.toml
Building image from Dockerfile...
Built image: agentkernel-my-app:a1b2c3d4
Creating sandbox 'my-app' with image 'agentkernel-my-app:a1b2c3d4'...

Images are cached based on content hash - subsequent creates reuse the cached image.

What Happens

Validates sandbox name
Loads config file (if provided)
Builds Dockerfile (if configured)
Creates container/VM with specified resources
Saves sandbox state to ~/.local/share/agentkernel/sandboxes/

The sandbox is created but not started. Use agentkernel sandbox start to run it.