Commands

agentkernel provides a Docker-like CLI for managing sandboxes.

Quick Reference

Daily Drivers (Root Level)

Command	Description
`run`	Run a command in a temporary sandbox
`exec`	Execute a command in a running sandbox
`attach`	Attach to a sandbox's interactive shell
`receipt`	Verify and replay execution receipts

Sandbox Lifecycle (`sandbox` / `sb`)

Command	Description
`sandbox create`	Create a new sandbox
`sandbox start`	Start a stopped sandbox
`sandbox stop`	Stop a running sandbox
`sandbox remove`	Remove a sandbox
`sandbox list`	List all sandboxes (with IP addresses)
`sandbox info`	Show detailed information about a sandbox (with IP)
`sandbox extend-ttl`	Extend a sandbox's time-to-live
`sandbox cp`	Copy files to/from a sandbox
`sandbox gc`	Garbage-collect expired sandboxes
`sandbox clean`	Remove all sandboxes and Docker artifacts
`sandbox exec-list`	List running exec processes
`sandbox exec-logs`	View exec process logs
`sandbox exec-kill`	Kill a running exec process

SSH (`ssh`)

Command	Description
`ssh connect`	SSH into a sandbox (certificate-authenticated)
`ssh config`	Generate SSH config entry for IDE integration
`ssh proxy`	ProxyCommand helper for SSH

Templates & Configuration

Command	Description
`template list`	List available templates (built-in + custom)
`template save`	Save a running sandbox as a template
`template add`	Add a template from GitHub
`template remove`	Remove a custom template
`sandbox export-config`	Export sandbox config as TOML
`sandbox import-config`	Create sandbox from a TOML config

Snapshots & Sessions

Command	Description
`snapshot take`	Save a sandbox's current state
`snapshot list`	List all snapshots
`snapshot delete`	Delete a snapshot
`snapshot restore`	Restore a sandbox from a snapshot
`session start`	Start an agent session (sandbox + agent)
`session list`	List all sessions
`session stop`	Stop a session
`session save`	Save a session (snapshot + metadata)
`session resume`	Resume a stopped/saved session
`session delete`	Delete a session

Pipelines & Parallel Execution

Command	Description
`pipeline`	Run a multi-step pipeline (TOML-defined)
`parallel`	Run multiple jobs concurrently

Volumes

Command	Description
`volume create`	Create a persistent volume
`volume list`	List all volumes
`volume info`	Show volume details
`volume delete`	Delete a volume

Image & Disk Management

Command	Description
`build`	Build a custom image from Dockerfile
`images list`	List Docker images (with sandbox usage)
`images local-list`	List locally built images
`images local-delete`	Delete a locally built image
`images local-sync`	Sync metadata with Docker
`images prune`	Remove unused images
`images pull`	Pull a Docker image
`sandbox export`	Export sandbox filesystem as tar

Secrets

Command	Description
`secret set`	Store a secret
`secret get`	Retrieve a secret
`secret list`	List stored secret keys
`secret delete`	Delete a secret

System & Diagnostics

Command	Description
`setup`	Configure agentkernel and backends
`doctor`	System diagnostics and health check
`stats`	Show usage statistics from audit log
`benchmark`	Benchmark sandbox backends
`completions`	Generate shell completions (bash, zsh, fish)
`agents`	List supported AI agents and availability
`plugin`	Manage agent plugins
`daemon`	Manage the VM pool daemon
`audit`	View and manage audit logs
`replay`	Replay a recorded session
`receipt verify`	Verify execution receipt integrity
`receipt replay`	Replay a recorded command invocation

Global Options

--help, -h      Show help
--version, -V   Show version

Common Workflows

# One-shot execution
agentkernel run python3 script.py

# Persistent sandbox
agentkernel sandbox create my-sandbox --template python -B docker
agentkernel sandbox start my-sandbox
agentkernel exec my-sandbox -- python3 --version
agentkernel sandbox stop my-sandbox

# Per-branch sandboxes (auto-named from git project + branch)
agentkernel sandbox create --branch -B docker

# Interactive development
agentkernel sandbox create dev --config agentkernel.toml
agentkernel sandbox start dev
agentkernel attach dev

See individual command pages for detailed examples: run, create, snapshots, sessions, pipelines, volumes, images, receipts.

Audit Logging

All sandbox operations are logged to ~/.agentkernel/audit.jsonl as JSONL. Each entry includes timestamp, pid, user, and the event payload. Set AGENTKERNEL_AUDIT=0 to disable.

agentkernel audit                          # list recent events
agentkernel audit --sandbox my-sandbox     # filter by sandbox
agentkernel audit --path                   # show log file path

Event	When
`sandbox_created`	`sandbox create`
`sandbox_started`	`sandbox start`
`sandbox_stopped`	`sandbox stop`
`sandbox_removed`	`sandbox remove`
`command_executed`	`exec` / `run`
`file_written`	`sandbox cp` to sandbox
`file_read`	`sandbox cp` from sandbox
`session_attached`	`attach`
`ssh_connected`	`ssh connect`
`ssh_disconnected`	`ssh connect` (disconnect)
`policy_violation`	Blocked command