Docs · Quickstart

Run your first
governed agent.

Five minutes from zero to proof. Install the CLI, configure a tenant, dock an agent, issue a lease, run it, and read the signed receipt it leaves behind. Every step names the mechanism it exercises.

Time ~5 min Needs a terminal + a tenant Result one signed receipt

Install the CLI

The Dragons CLI docks agents, issues leases, and reads the WorkLedger from your terminal. Install it once.

# install the Dragons CLI
curl -fsSL https://dragons.dev/install.sh | sh

# verify
dragons --version
# dragons 1.0.0

The CLI talks to your tenant runtime. In side-by-side mode it governs your agents without changing how they execute.

Configure a tenant

Point the CLI at your tenant and authenticate. The tenant is the isolation boundary — every lease and receipt lives inside it.

# dragons.toml
[tenant]
id   = "tnt_019e5e66dca079278437f7524903d418"
name = "acme-prod"

[runtime]
# runtime truth stays tenant-local
endpoint = "http://127.0.0.1:7878"

Set your API key in the environment so it never lands in the config file or the ledger.

export DRAGONS_API_KEY="sk_live_..."

Dock your first agent

Docking records the agent’s manifest_hash — a SHA-256 fingerprint over its code, config, and capabilities. Nothing runs under an unrecorded manifest.

dragons dock \
  --agent ./my-agent \
  --name "invoice-runner"

# → docked  invoice-runner
# → manifest_hash  sha256:a3f9c1e8...4b2d
# → organism state  stopped

The agent is now a known identity in the tenant. It is docked but not yet authorized to act.

Issue a lease and run

A lease is a time-bounded, scope-restricted grant. No lease, no execution. Issue one, then run the agent under it.

# grant: read invoices, write receipts, for 1 hour
dragons lease issue \
  --agent invoice-runner \
  --scope "invoices:read,receipts:write" \
  --ttl 1h

# → lease  lse_019e5e7f...  active  expires 2026-05-28T05:12Z

dragons run invoice-runner
# → organism state  running
# → heartbeat  ok  (pulse + progress)

The agent now executes under a signed lease. The control plane tracks its organism state from compulsory heartbeats — running, degraded, autohealing — instead of a wall-clock timeout.

View the receipt

When the work cycle completes, Dragons appends a signed, hash-chained receipt to the WorkLedger. Read it back to see the proof.

dragons ledger tail --agent invoice-runner --last 1

The receipt is the unit of audit. It is append-only and chained to the receipt before it, so the ledger is tamper-evident and a third party can replay goal → action → evidence → outcome.

receipt_id     rcp_019e5e80a1f3...
manifest_hash  sha256:a3f9c1e8...4b2d
lease_ref      lse_019e5e7f...
prev_hash      sha256:0000...root
payload_hash   sha256:7d2b...e904
outcome        accepted
signature      ed25519:c4f1...verified

Next steps

You have a signed receipt. Now go deeper on the concepts behind it.

Concepts

The four mechanisms in depth: identity, leases, evidence, liveness.

WorkLedger & evidence chain

How receipts hash-chain and how a third party replays them.

Organism state & liveness

Heartbeats, degrade thresholds, autoheal, and quarantine.

Security & trust

Governance model, audit posture, data handling, disclosure.

CLI reference

Every command for dock, lease, ledger, and status.

API reference

The HTTP API and SDK: types, endpoints, error codes.

If you get stuck

Three doors out.

Most snags are answered below. If none of these fit, send a reproduction; we read every message.

FAQ Buyer + operator objections answered against the mechanism — Temporal, build-it-yourself, license, observability tools, trial scope. Email hello@dragons.dev — paste the failing command, the output, and your tenant id. A human replies. Early access If you need a tenant to run the quickstart against, request one. Side-by-side mode is one agent, one lease, one signed receipt.