60-second quickstart¶

You will need

Go 1.26+ to build the CLI, Docker for the sandbox backend, and a free Groq API key for the example agent. Firecracker is optional — the CLI auto-detects a backend and falls back to Docker.

Verified end to end on Linux + Docker against constle v0.4.0. Copy-paste as-is.

1. Build the CLI (Go 1.26+):

git clone https://github.com/constle/constle
cd constle
go build -o constle ./cmd/constle

Pre-built binaries for Linux, macOS, and Windows are on the releases page; see Verifying a release before you trust one.

2. Check the example manifest without running anything:

./constle validate examples/basic-agent/agent.yaml

✓ examples/basic-agent/agent.yaml is valid

  name:        basic-agent
  version:     0.1.0
  isolation:   network (inferred from capabilities)
  image:       basic-agent:latest
  memory:      512MB
  allowed:     api.groq.com

⚠️  warning: spending limits are declared but NOT enforced:
   no mcp.servers entry declares a pricing block, so there is nothing to meter.

That warning is the design working. examples/basic-agent/agent.yaml declares max_per_run_usd: "0.10" but has no priced MCP server, so there is nothing to meter it against — and Constle says so out loud rather than letting a declared cap look real. See Known limitations.

3. Build the example agent image and run it:

docker build -t basic-agent:latest examples/basic-agent
export GROQ_API_KEY=gsk_...            # free key: https://console.groq.com
export AGENT_TASK="What is 2+2?"
./constle run examples/basic-agent/agent.yaml

constle v0.4.0

  → parsing examples/basic-agent/agent.yaml
  ✓ Agentfile valid
     agent:     basic-agent v0.1.0
     isolation: network
     memory:    512MB
     network:   restricted → api.groq.com
     spending:  run≤$0.10 (NOT ENFORCED — no priced MCP servers)

  → detecting backend
  ✓ backend: docker

  → starting sandbox...
  ✓ sandbox started (run_id: 76935e132f9be8e9)

  ┌─ agent output ──────────────────────────
  │ 2 + 2 = 4
  └─────────────────────────────────────────

✓ run finished    exit=0    duration=2.7s
  audit log: ~/.constle/logs/basic-agent-2026-08-08.jsonl

constle run takes no --env flag. Exactly three host variables are forwarded into the sandbox — GROQ_API_KEY, ANTHROPIC_API_KEY, and AGENT_TASK (internal/sandbox/docker.go, forwardedHostEnv). Export them in your shell; they are never written into the image or the manifest.

4. Sign the audit trail (optional, ~20 seconds more):

./constle identity create my-agent --owner=you@example.com

Paste the printed did:key:... into the manifest under identity.did, run again, then:

./constle audit verify ~/.constle/logs/my-agent-$(date -u +%F).jsonl

✓ audit log verified: ~/.constle/logs/my-agent-2026-08-08.jsonl

  entries:   2 (all signatures valid, hash chain intact)
  signed by: did:key:z6MkgroKowQYDZjDmqbn82mJv4YFPKowS2xDhxGYrp4u3P1o

Edit a single byte of that file and re-run it:

error: TAMPERING DETECTED in ~/.constle/logs/my-agent-2026-08-08.jsonl
  line 1: invalid_signature — signature does not verify against did:key:z6Mkg… — the entry was edited after signing

With identity.did set, constle run also fails closed: if the manifest names a DID with no matching private key on this machine, the run refuses to start rather than proceeding under an identity it cannot actually prove.

Where to go next¶

The Agentfile — every field the runtime consumes, and what each one is actually enforced by.
Architecture — what the sandbox, the proxy, and the gates are each doing during that run.
Known limitations — why the run above printed NOT ENFORCED, and four other gaps like it.