Skip to content

agentkernel sandbox start / stop / pause / resume / fork

Manage the lifecycle of persistent sandboxes.

start and stop are the portable lifecycle operations. Firecracker sandboxes on x86_64 Linux/KVM also support full-state pause, resume, and fork, which preserve guest memory and process state. These full-state operations remain a preview with native validation requirements.

start

Start a stopped sandbox.

Firecracker sandboxes are started through the long-running local API server so the VM process survives after the CLI exits. Run agentkernel serve first; AGENTKERNEL_PORT selects a non-default local port. If the server requires an API key, set AGENTKERNEL_API_KEY for delegated CLI requests. For a TLS-only TCP listener, use the private Unix control socket and set AGENTKERNEL_CONTROL_SOCKET in the client.

Each ordinary Firecracker start owns an AgentKernel-managed writable rootfs lineage. The opaque lineage reference is stored with the sandbox state and is reopened after stop, so guest filesystem changes survive a cold start.

Set AGENTKERNEL_ROOTFS_COW_MAX_BYTES to a host-wide logical-byte cap for durable Firecracker writable images. A new start fails before copying its base image when existing COW images plus that image would exceed the cap. This is a storage headroom guard, not a tenant quota; it applies to every local Firecracker sandbox and counts stopped lineages as well as running ones.

Before delegating, the CLI resolves the saved agentkernel.toml permissions and startup file injections. It stores that resolved configuration in a private host manifest and sends only an unguessable one-shot reference in the local start request. The manifest is bound to the sandbox UUID and owner, consumed on the first attempt, expires after five minutes, and is scrubbed on removal. A valid reference can authorize the server's first claim of an unowned local sandbox even after the server restarted or previously inspected it. This preserves the selected profile, network and mount behavior, resource limits, and file contents while the server retains VM ownership, without exposing a public capability-escalation payload.

Usage

agentkernel sandbox start [OPTIONS] <NAME>

Options

Option Description
-B, --backend <BACKEND> Override backend (usually auto-detected from saved state)

Examples

# Start a sandbox
agentkernel sandbox start my-sandbox

# Verify it's running
agentkernel sandbox list

What Happens

  1. Loads sandbox configuration from disk
  2. Resolves its permissions and startup files
  3. Uses the backend that was used when creating the sandbox
  4. Starts the container/VM (through the local server for Firecracker)
  5. Sandbox is ready for exec; backends with interactive terminal support also allow attach

Server-owned Firecracker sandboxes do not support interactive attach. Use agentkernel exec <name> -- <command> or agentkernel ssh <name> when SSH is configured.

stop

Stop a running sandbox. Container/provider backends preserve their normal backend state and can be started again.

For Firecracker, the CLI delegates stop to the local API server that owns the VM process. Ordinary stop preserves the writable rootfs lineage for the next cold start. A Firecracker VM restored or forked from a full-state checkpoint still rejects ordinary stop: its memory/device checkpoint remains the source of truth. Use pause to create a new checkpoint or remove to discard it.

Usage

agentkernel sandbox stop <NAME>

Examples

# Stop a sandbox
agentkernel sandbox stop my-sandbox

# Verify it's stopped
agentkernel sandbox list
# NAME          STATUS     BACKEND
# my-sandbox    stopped    docker

What Happens

  1. Sends stop signal to the container/VM
  2. Waits for graceful shutdown
  3. Sandbox configuration and Firecracker writable-disk lineage are preserved on disk; backend persistence rules apply
  4. Can be started again when the backend's persistence contract allows it; full-state Firecracker lineages use pause and resume instead

pause (alias: suspend)

Pause a running Firecracker sandbox into a durable full-VM checkpoint.

Usage

agentkernel sandbox pause <NAME>
agentkernel sandbox suspend <NAME>

Example

agentkernel sandbox pause experiment-a
agentkernel sandbox list
# NAME             STATUS    BACKEND
# experiment-a     paused    firecracker

Unlike stop, pause captures guest memory, process state, virtual-device state, and an immutable disk checkpoint. The sandbox is not available for exec or attach while paused.

This operation requires the Firecracker backend on x86_64 Linux/KVM. Other backends return an unsupported-operation error. CLI pause, resume, and fork commands also require a healthy local agentkernel serve process because it owns the Firecracker VM.

resume

Resume a paused Firecracker sandbox from its full-VM checkpoint.

Usage

agentkernel sandbox resume <NAME>

Example

agentkernel sandbox resume experiment-a

The sandbox continues from the captured memory and process state instead of performing a fresh boot.

fork

Create a new running sandbox from a paused Firecracker sandbox.

Usage

agentkernel sandbox fork <SOURCE> --as <CHILD>

Example

agentkernel sandbox pause experiment-a
agentkernel sandbox fork experiment-a --as experiment-b

experiment-b starts immediately from the checkpoint. experiment-a stays paused, so it can be resumed or forked again. After the fork, source and child disk state diverge independently. The child inherits the source owner and tenant metadata atomically; cross-owner or cross-tenant forks are rejected before the child VM is restored.

Security warning: A fork copies guest memory and filesystem state. Any credentials captured in the checkpoint are duplicated into the child; rotate or revoke them when appropriate.

remove

Permanently delete a sandbox and its state.

For Firecracker, removal is delegated to the local API server so a live VM is stopped before its persisted state is deleted.

Usage

agentkernel sandbox remove <NAME>

Examples

# Remove a stopped sandbox
agentkernel sandbox remove my-sandbox

# Force remove a running sandbox (stops it first)
agentkernel sandbox remove my-sandbox

What Happens

  1. Stops the sandbox if running
  2. Removes the container/VM
  3. Deletes saved state from ~/.local/share/agentkernel/sandboxes/

Lifecycle Summary

create -> start -> stop -> start -> ... -> remove
            |
            +-> pause -> resume
                   |
                   +-> fork -> running child
State Can exec/attach? Full guest memory preserved? Persisted?
Created (not started) No No Yes
Running Yes In memory Yes
Paused (Firecracker) No Yes Yes
Stopped No No Configuration only; filesystem persistence is backend-specific
Removed - No No