Docs Getting started
Constle documentation
Constle is a runtime that enforces what an AI agent is allowed to do (network, spend, approvals, identity) from outside the agent, so a compromised agent cannot turn the rules off.
Early and pre-1.0
Constle is early and solo-maintained (v0.5.0, pre-1.0). Interfaces may still change before a 1.0 release. Read Known limitations before you rely on any of this.
Transcript
0:00 AI agents call APIs, spend money and touch real systems. And anything they read can steer them. If an agent's rules live inside the agent, one prompt injection can talk its way past them. Constle moves the rules outside the agent. They're enforced from the host, where the agent can't reach. Network. Spend. Approvals. Identity.
0:26 You declare all of it in one YAML file: the Agentfile.
0:31 In a sandbox with no default route, every connection goes through an allowlisting proxy — and undeclared hosts get a 403. Spend is metered at the tool-call boundary, and sensitive tool calls pause for a human. Every step lands in a signed, hash-chained audit log — so an edit after the fact shows up.
0:53 It isn't an agent framework: LangGraph, CrewAI or your own code run inside it, unchanged. Open source, Apache 2.0, written in Go. Version 0.5: pre-1.0, with its known limitations written down. Rules your agent can’t turn off.
You declare the policy in one YAML file, the Agentfile. Constle runs the agent inside a sandbox with no default route, routes every packet through an allowlisting proxy, meters cost at the tool-call boundary, pauses sensitive calls for a human, and writes a signed, hash-chained audit log. None of that lives in the agent's process, so there is nothing in it for a prompt injection to disable.
Three of the four layers ship today. The quickstart builds the CLI and runs a real agent under enforcement in about a minute.
Enforcement, demonstratedLink to this section
An agent whose manifest declares allowed_hosts: [api.groq.com], reaching for one declared host and one undeclared one:
┌─ agent output ──────────────────────────
│ https://api.groq.com/ CONNECT allowed TLS tunnel opened, server replied
│ https://evil.example.com/ CONNECT refused Tunnel connection failed: 403 Forbidden
└─────────────────────────────────────────
$ grep network ~/.constle/logs/egress-probe-2026-08-08.jsonl
{"event":"network_allowed","details":{"bytes":5314,"host":"api.groq.com","http_status":200,"method":"CONNECT"}}
{"event":"network_blocked","details":{"bytes":3404,"host":"evil.example.com","http_status":403,"method":"CONNECT"}}The second request never left the sandbox: the proxy declined to open the tunnel. Both attempts land in the audit log either way; the blocked one is how you find out it happened. Raw-IP bypass attempts, IPv6 and the DNS trust boundary are covered in Network isolation.
What Constle enforcesLink to this section
Nine capabilities. Eight ship today.
| Capability | Mechanism | Status |
|---|---|---|
| Sandboxed execution | Firecracker microVM (hardware isolation) or a two-network Docker sandbox with no default gateway. Auto-detected, or forced with --backend=docker|firecracker. A declared isolation: level is a minimum: it may be stronger than the declared capabilities require but never weaker, or the Agentfile is rejected at validate time. isolation: kernel selects Firecracker and the run fails closed if Firecracker is unavailable, unless an operator explicitly accepts a weaker boundary with --accept-isolation=<level>, which is named and recorded. |
Shipped |
| Network egress | All egress traverses a Squid proxy allowlisting network.allowed_hosts. Matching is name-based (dstdomain) with reverse lookups off, so a raw IP is denied, including the real IP of an allowed host and an address whose PTR record names one. Destinations in loopback, link-local, metadata and private ranges are refused on the resolved address, and CONNECT is confined to 443. Every allow and every block is an audit event. |
Shipped |
| Max duration | The agent is killed when limits.max_duration_seconds elapses; the kill is recorded as terminated_by_limit. |
Shipped |
| Audit log | JSONL per agent per UTC day. With identity.did set, every entry is Ed25519-signed and hash-chained; constle audit verify detects tampering and reports the offending line. A gate decided over the signed webhook also records the approver's signed decision, which constle audit verify --agentfile=… re-verifies. |
Shipped |
| Spending limits | Hard max_per_run_usd and max_per_day_usd, metered at the MCP gate against each server's declared pricing. The daily ledger is durable across runs, keyed by DID so a rename can't reset it. A priced server whose response omits a declared usage value kills the run. Scope caveats: limitations 2 and 3. |
Shipped |
| Human gates | Declared MCP servers are reachable only through a protocol-aware gate proxy. A matching tools/call pauses for approval at the terminal and, with approver_pubkey set and a notify webhook URL resolving, at a signed decision channel too; the first decision wins. A decision that arrives is verified and can only deny. With no decision by the deadline, on_timeout decides (default abort). Matching caveat: limitation 1. |
Shipped |
| Cryptographic identity | W3C did:key (Ed25519). The private key stays at ~/.constle/identities/<name>/ (mode 0600) and never enters the sandbox. constle run fails closed on a declared DID with no local key. |
Shipped |
| Agent-to-agent messaging | Signed envelopes to explicitly declared peers only. The host signs and verifies; the sandbox does no cryptography and never sees a peer's real endpoint. No discovery mechanism exists, by design. Replay caveat: limitation 4. | Shipped |
| Agent commerce | Agents discovering and paying each other for work. A direction, not a scheduled milestone. | Not built |
Every layer runs in the host constle process: the agent's private key, the real MCP server URLs and the real A2A peer endpoints never enter the sandbox. Constle is not a framework: it doesn't decide how an agent reasons or plans, and LangGraph, CrewAI or hand-rolled code run inside it unchanged. More in What Constle is not.
Find your way aroundLink to this section
Getting started
- QuickstartBuild or install the CLI, validate a manifest, run an agent in a sandbox, sign and verify its audit log, and gate a tool call.
- Known limitationsFive places where an Agentfile field currently looks stronger than the runtime is, each traced to the code that makes it so.
- What Constle is notNot a framework, not a cloud, not a monitoring overlay, not finished, not closed. Where Constle's job starts and stops.
How it works
- ArchitectureConstle's four layers (runtime and sandbox, identity and governance, communication, and the planned commerce layer) and the chokepoints where each rule is enforced.
- Network isolationHow the sandbox's no-default-route topology and the Squid allowlist proxy combine into a network policy the agent cannot step around, and where that stops.
- Spend caps & meteringHard per-run and per-day USD caps, metered at the MCP gate against each server's declared pricing, and exactly which traffic that does not cover.
- Human gatesPause named MCP tool calls until a human decides, at the terminal or through an Ed25519-signed webhook decision, and exactly what happens when nobody answers.
- Audit log & verificationThe signed, hash-chained JSONL audit log, how constle audit verify catches an edited, deleted or reordered line, and what an intact chain does and does not prove.
- IdentityEach agent's W3C did:key (Ed25519) identity, where its private key lives, how a run fails closed without it, and how it signs the audit log.
- Agent-to-agent (A2A)Signed agent-to-agent calls between explicitly declared peers, signed and verified by the host, delivered into the sandbox only after verification.
Reference
- The AgentfileOne declarative YAML file describing what an agent needs, enforced identically wherever the runtime is installed. An annotated example, the enforcement labels, and the sections at a glance.
- Field referenceThe complete AgentManifest specification: every section, field, type, default, validation rule and enforcement label.
- CLI referenceEvery constle subcommand and flag, the environment variables it reads, and the startup screen.
- Verifying a releaseCheck a Constle release's cosign signature and checksums before you trust the binary, and what the one-line installer verifies for you.
Project
Something wrong or unclear? Open an issue. The specifications on these pages are copies of spec/ in constle/constle.