Capabilities

This is the complete map of what Treeship does, organized by purpose rather than by version. Each capability lists what it is, how to use it, and how to test it (a command and the output you should see). A Since tag marks the release it shipped in.

If you are testing a build, work top to bottom; the layers build on each other. For a guided first run with "you are on track when" checkpoints, start with What to expect.

The layers at a glance

Layer 0: The signing model

Everything above the line is built on a handful of primitives that predate the agent stack. This is the "hello world" of Treeship: sign something, verify it, record a session. All of it runs locally, against no server.

Sign, verify, and the artifact

Since 0.1.0

What: Every artifact is a DSSE envelope (a standard signed-message format) over a canonical JSON payload (RFC 8785, so the exact bytes are reproducible), signed with Ed25519. treeship init creates your ship and key; attest action signs a record that an agent did something; verify re-checks the signature and the parent chain. These three are the atoms; every card, receipt, and session is built from them.

Use / Test:

treeship init --name me
treeship attest action --actor agent://me --action "tool.call"
treeship verify <artifact-id>
# expect: ✓ verified (1 artifact · chain intact)

Wrap any command

Since 0.1.0

What: treeship wrap -- <cmd> runs any command and attests its execution (the command, exit code, and optional output digest) as a signed artifact. The zero-integration way to get a receipt for something.

Use / Test:

treeship wrap -- git commit -m "ship it"
treeship log   # the wrapped command appears as a signed artifact

Session recording and the .treeship package

Since 0.5.0, hardened through 0.11.x

What: session start / session close bracket a unit of work; everything the agent does in between is captured into a sealed, portable .treeship package containing a session receipt, the artifact chain, and a Merkle root. session report uploads it and returns a shareable URL. session abandon quarantines a wedged session without losing evidence. At close, Treeship reconciles file and git changes so edits made outside captured tool channels still land in the receipt.

Use / Test:

treeship session start --name "my task"
# ... agent does work ...
treeship session close --headline "done"
# expect: "session receipt composed" with a package path and a merkle root
treeship package verify .treeship/sessions/<id>.treeship

The Merkle log and checkpoints

Since 0.5.0

What: Every artifact hash is appended to a local Merkle tree (a tamper-evident structure where any change breaks the root). treeship checkpoint seals and signs a root over your artifacts; inclusion proofs let anyone confirm a specific artifact is in that root. This is the substrate the whole transparency layer (Layer 5) is built on.

Use / Test:

treeship checkpoint
treeship merkle proof <artifact-id>   # generates an inclusion proof

Trust roots and the trust model

Since 0.9.x

What: Verification is always against your pinned trust roots, never a server's say-so. treeship trust add pins a key under a kind (ship, hub_checkpoint, agent_cert, session_host). A self-signed forgery does not verify, because its key is not pinned. This is the client-decides invariant that makes every other layer trustworthy.

Use / Test:

treeship trust list
treeship trust add key_… ed25519:… --kind ship --yes

Connecting a hub

Since 0.9.x · network

What: treeship hub attach connects your machine to a hub over a device flow (approve in a browser, like signing into a TV app). The hub stores signed artifacts and answers lookups; it holds no secrets and verifies nothing.

Layer 1: Identity

Give an agent a cryptographic identity so its actions are provably its own, not just labeled.

Per-actor signing (a provable actor)

Since 0.13.0

What: An agent can sign with its own dedicated key instead of the shared ship key, so treeship verify reports actor proof: proven (key-bound) rather than asserted. The runtime holds the key; the agent cannot read it.

Use:

treeship agent register --name deployer --own-key
treeship attest action --actor agent://deployer --action "Bash(git:commit)"

Test:

treeship verify <artifact-id>
# expect: actor proof: proven (key-bound)

Idempotent registration

Since 0.15.0

What: Re-running register --own-key for an agent reuses its existing key instead of minting a duplicate. Safe to call on every startup, which is what the bridges do. A --quiet flag skips writing the on-disk .agent package for programmatic callers.

Test:

treeship agent register --name deployer --own-key
treeship agent register --name deployer --own-key   # runs clean, no second key
treeship keys list | grep -c key_   # count is stable

Certificate-chain delivery (pin the ship, verify the fleet)

Since 0.17.0 · network

What: Registering an agent also mints a signed agent_cert.v1 binding the agent to its key, issued by your ship. publish pushes the chain; a counterparty who pins your ship key can then verify every agent it certifies, without pinning each one. This is how browsers trust millions of sites from a few root certificates.

Use:

treeship publish agent://deployer   # pushes card + cert chain

Test (as a third party holding only your ship key):

treeship resolve --hub https://api.treeship.dev agent://deployer
# expect: signature: verified (chain to pinned ship root)

Layer 2: Capability cards

A capability card is a signed document listing what an agent is allowed to do, with each capability graded by how strongly it is known.

Agent capability cards (agent_card.v1)

Since 0.13.0

What: attest card mints a signed card declaring an agent's identity and tool set. verify-capability cross-checks it against the agent's actual signed actions and reports in-scope vs out-of-scope.

Use:

treeship attest card --agent agent://deployer --tools "file.*,db.query"

Test:

treeship verify-capability <card-id>
# expect: key-bound: yes (AgentCert) · status: verified

Provenance grades (captured / exercised / discovered / declared)

Since 0.14.0 (captured/exercised/declared), 0.15.0 (discovered)

What: Every capability on a card carries where it came from: captured (read from real config), exercised (proven by real receipts of use), discovered (the agent's own descriptor), declared (a typed claim). Strongest to weakest, always labeled, never mixed silently.

Test:

treeship verify-capability <card-id>
# expect a mix line: "9 captured, 2 exercised, 0 declared-only"

Three ways to build a card

Since 0.14.0–0.15.0

What:

• --from-harness <settings.json> captures the tool set from a real config → graded captured (strongest).
• --tools-json <file> records an operator's explicit list → graded declared.
• --from-a2a <AgentCard.json> maps an agent's own published skills → graded discovered.

Use / Test:

treeship attest card --agent agent://deployer --from-harness ~/.claude/settings.json
# expect: "N of N captured from harness"

Capability-card revocation

Since 0.13.0

What: revoke-capability mints a signed revocation. verify-capability honors it only when the revoker is authorized (the card's own key or a Ship trust root) and then reports status: REVOKED. An unauthorized revocation is ignored (fail-closed).

Test:

treeship revoke-capability <card-id> --reason "rotated"
treeship verify-capability <card-id>
# expect: status: REVOKED, and a non-zero exit code

Glob capability matching (Bash(git:*))

Since 0.16.0

What: Capability patterns match with a wildcard anywhere in the string, so harness-captured patterns like Bash(git:*) and Read(*) correctly match Bash(git:status) while still rejecting Bash(gh:pr).

Test:

# a card declaring Bash(git:*), with a real Bash(git:status) action
treeship verify-capability <card-id>
# expect the git action counted in-scope, not flagged

Browser verification

Since 0.13.0

What: The same verification runs in a browser via WebAssembly, returning the identical verdict to the CLI. A receipt viewer can show key-bound status with no server.

Test: open a published receipt at treeship.dev/verify/<artifact-id> and confirm the verdict matches the CLI.

Layer 3: Typed receipts

Under every card and action is a signed receipt. The predicate registry makes specific receipt kinds typed and schema-checked.

Predicate registry

Since 0.13.0

What: Registered receipt kinds (memory.write.v1, boundary.v1, agent_card.v1, session.v1, agent_cert.v1, profile.v1, and more) are validated against a JSON Schema before signing. A malformed payload is rejected, so a downstream verifier can rely on the shape, not just the signature.

Test:

treeship attest receipt --system system://x --kind session.v1 --payload '{}'
# expect: rejected with the missing required field named

External proof receipts

Since 0.12.0, extended 0.13.0

What: attest receipt --payload-file / --payload-digest sign over a payload read from a file or recorded as a digest, for large or out-of-band proofs (memory systems, external services).

Layer 4: Authorization

Beyond "who did what": who is allowed to, single-use permission grants, delegation between agents, and multiple agents in one accountable session.

Scoped approvals with replay protection

Since 0.9.6–0.9.9

What: attest approval mints a signed permission grant scoped to a specific actor, action, and subject, with a --max-uses limit. attest action consumes a grant before signing, via a local Approval Use Journal that is append-only, so a grant with --max-uses 1 cannot be replayed even across separate runs. verify reports the replay posture: package-local, journal-local, or hub-verified.

Use:

treeship attest approval --approver human://alice \
  --allowed-action "stripe.charge.create" --allowed-actor agent://deployer --max-uses 1
treeship attest action --actor agent://deployer --action "stripe.charge.create" --approval-nonce <nonce>

Test:

# a second consume of a max-uses=1 grant must fail
treeship attest action --actor agent://deployer --action "stripe.charge.create" --approval-nonce <same-nonce>
# expect: refused (max uses exceeded)

Handoffs (delegation between agents)

Since 0.9.x, A2A-wired 0.15.0

What: attest handoff records one agent transferring artifacts (and optionally inherited approvals and obligations) to another, as a signed delegation boundary. The A2A bridge emits these automatically when agents delegate tasks.

Use / Test:

treeship attest handoff --from agent://planner --to agent://executor --artifacts <id>
treeship verify <handoff-id>   # a signed, verifiable delegation record

Agent invitations and multi-agent rooms

Since 0.11.0

What: session invite mints a signed, single-use, expiring grant that lets a second agent join an existing session; session join and session countersign complete a two-signature handshake (the joiner asserts "I'm joining," the host countersigns "I observed this join"). Backed by a SessionHost trust root so a forged invitation is quarantined. This is how multiple agents share one accountable session.

Use / Test:

treeship session invite <session-id> --invitee-pubkey ed25519:…
# the invitee runs: treeship session join --invite <blob> --actor agent://helper
# the host runs:    treeship session countersign <participant-id>

Trust templates

Since 0.11.0

What: Ready-made trust configurations for common patterns (for example the Robinhood agentic-trading template) so a new user starts from a worked setup rather than a blank config.

Layer 5: Transparency log

An append-only, monitorable history of an agent's receipts, with tampering detectable. This is Certificate Transparency, for agents.

Publish and anchor

Since 0.14.0 · network

What: publish pushes an agent's resolvable set to a hub. merkle checkpoint + merkle publish seal a signed Merkle root over your artifacts and push per-artifact inclusion proofs. The hub stores; it never generates or verifies. Checkpoints are computed publisher-side.

Use:

treeship publish agent://deployer
treeship checkpoint && treeship merkle publish

Test:

treeship resolve --hub https://api.treeship.dev agent://deployer
# expect: transparency: anchored & verified (checkpoint #N)

Audit (with omission detection)

Since 0.14.0 · network

What: audit --hub pulls an agent's history and re-verifies each anchored entry's inclusion offline, then checks completeness against the agent's committed anchor: it reports OMISSION if the hub dropped committed receipts.

Use / Test:

treeship audit --hub https://api.treeship.dev agent://deployer
# expect: "N/N verified", "complete", or a named anomaly

Monitor mode

Since 0.14.0 · network

What: audit --watch re-audits on an interval and keeps alerting. A monitor that finds a rewritten log keeps firing instead of forgiving it.

Cryptographic append-only proof

Since 0.15.0 · network

What: audit proves a hub's log was only appended to since you last saw it (the true no-rewrite guarantee), by re-verifying a Merkle consistency chain the publisher generated. It warns append-only INVALID — possible history rewrite if the chain fails.

Test:

treeship audit --hub https://api.treeship.dev agent://deployer
# expect: "append-only VERIFIED" once you have witnessed two checkpoints

Layer 6: Resolution

Look up any agent by its URI and re-verify it against your own trust roots. DNS, OCSP, and Certificate Transparency, for agents.

Local and network resolution

Since 0.13.0 (local), 0.14.0 (network)

What: resolve <agent> re-derives an agent's verifiable bundle from local artifacts. resolve --hub <url> <agent> pulls it over the network and re-verifies everything client-side. The hub's word is never trusted.

Use / Test:

treeship resolve agent://deployer                                   # local
treeship resolve --hub https://api.treeship.dev agent://deployer    # network
# expect a full verdict with signature, key-bound, transparency lines

Layer 7: The handshake

Verify an agent with the agent handing you its proof, no registry in the loop, then prove it controls its key right now. See The Agent Handshake.

Onboard (nothing to verifiable, one command)

Since 0.17.0

What: Composes register → card → optional publish + anchor → trust bundle. Idempotent; safe on every agent boot. Ends by printing the exact commands a counterparty runs to trust you.

Use / Test:

treeship onboard deployer --from-harness ~/.claude/settings.json --publish
# expect steps [1/4]..[4/4] and a printed trust bundle

Keys export (the trust handshake)

Since 0.16.0

What: Prints your public key in pinnable form plus the exact trust add command a counterparty runs. The out-of-band half of the trust model; the private key never leaves the store.

Use / Test:

treeship keys export
# expect an ed25519:… pubkey and ready-to-run trust add lines

Presentation (carry your proof, verify offline)

Since 0.17.0

What: present writes one file with the agent's card, certificate chain, revocations, and a Merkle staple (checkpoint + inclusion proof). verify-presentation re-verifies it fully offline against your trust roots, with an explicit freshness bound (--max-staple-age).

Use / Test:

treeship present agent://deployer
treeship verify-presentation deployer.presentation.json --max-staple-age 1h
# expect: status: verified (key-bound, anchored)

Challenge mode (prove it is live)

Since 0.17.0

What: A static presentation proves the record; a challenge proves the bearer controls the key right now. The verifier mints a nonce; the agent signs it; the verifier checks the signature against the key the card established. Replay-resistant.

Use / Test:

NONCE=$(openssl rand -hex 16)
treeship present agent://deployer --challenge $NONCE
treeship verify-presentation deployer.presentation.json --challenge $NONCE
# expect: status: verified (key-bound, anchored, live)

Layer 8: Work history

Every session becomes a signed record; the records form a track record you can query, aggregate, and match against. See the work-history spec.

Session records (session.v1)

Since 0.16.0

What: session close mints a typed, signed record of the session: headline, outcome, tools exercised (computed from receipts), and an attestation class (self / runtime / countersigned) describing how the evidence was captured.

Test:

treeship session start --name test && treeship session close --headline "test"
# expect: "record: art_… (session.v1, class=…)"

History (the sortable projection)

Since 0.18.0 · network optional

What: history <agent> lists the agent's session records, filterable by --class and --since. Each envelope is re-verified on your machine; anchored entries' inclusion is re-proved offline.

Use / Test:

treeship history agent://deployer --hub https://api.treeship.dev
# expect a newest-first list; each row shows sig verified/unverified and anchor status

Profile (checkpoint-pinned track record)

Since 0.18.0

What: profile <agent> aggregates the history at a pinned checkpoint (sessions by class, actions, tools, span). --attest signs it as a claim. verify-profile recomputes every number from the log at that checkpoint: match grades it checked, mismatch is provably false. Reputation pinned to a root cannot drift.

Use / Test:

treeship profile agent://deployer --attest
treeship verify-profile <profile-id>
# expect: "checked — every number recomputed from the log and matched"

Match (find agents by exercised evidence)

Since 0.18.0 · network

What: match --exercised "<glob>" finds agents whose sessions actually exercised matching tools, ranked by verified session count. The hub proposes candidates from its index; the client re-verifies every record locally. Declared capability gets an agent found; exercised history gets it chosen.

Use / Test:

treeship match --hub https://api.treeship.dev --exercised "Bash(git:*)"
# expect ranked candidates, each with verified session counts

Layer 9: Protocol bridges

Provable receipts inside the protocols agents already speak, by default.

MCP bridge (@treeship/mcp)

Since 0.15.0

What: On startup the bridge provisions the agent's own key, so its MCP tool-call receipts verify as proven (key-bound). Best-effort and idempotent; if Treeship is missing it degrades gracefully.

Use: add @treeship/mcp as an MCP server; it captures actions automatically.

A2A bridge (@treeship/a2a)

Since 0.15.0, handoffs fixed 0.17.1

What: The middleware provisions its key and signs task and handoff receipts. Delegation boundaries between agents are recorded as signed handoffs.

Test: run a task through the A2A middleware and confirm a handoff artifact is produced and verifies.

Layer 10: Reliability

The properties that make the above trustworthy in practice, not just in theory.

Honest verdicts (exit codes + JSON)

Since 0.17.1

What: resolve, audit, verify-capability, verify-presentation, and verify-profile exit non-zero on a hostile verdict (revoked, violation, omission, rewrite, invalid proof) and emit one structured object under --format json. Scripts, CI, and monitors can gate on them.

Test:

treeship audit --hub https://api.treeship.dev agent://deployer --format json
echo "exit: $?"   # non-zero if a hostile verdict was detected

Self-healing keystore

Since 0.16.0

What: The machine key wrapping your private keys derives from a hardware identifier, so a hostname or username change no longer bricks the keystore. Older keystores are recovered automatically and re-wrapped.

Store visibility

Since 0.18.0

What: status shows which .treeship store it resolved (project-local vs global), so you always know which keystore a command used.

Test:

treeship status | grep store:
# expect: store: project-local -- /path/.treeship/config.json

Hardened hub

Since 0.18.0 · server-side

What: Request-body size caps, indexes on the public lookup paths, enforced foreign keys, idempotent checkpoint inserts, no internal error leakage on the public verify endpoint, and a full test suite on the DPoP authentication boundary.

How to run a full test pass

To exercise everything end to end, follow this order (each step's output is described above):

1. treeship init
2. treeship onboard tester --from-harness ~/.claude/settings.json
3. treeship attest action --actor agent://tester --action "Bash(git:status)"
4. treeship verify <id> → proven (key-bound)
5. treeship verify-capability <card-id> → verified
6. treeship hub attach, then treeship onboard tester --from-harness … --publish
7. treeship checkpoint && treeship merkle publish
8. From a clean config, pin the trust bundle, then treeship resolve --hub … agent://tester → verified (chain to pinned ship root), anchored & verified
9. treeship present agent://tester --challenge $(openssl rand -hex 16) and verify with the same nonce → live
10. treeship session close on a real session, then treeship history, treeship profile --attest, treeship verify-profile

If every step matches its expected output, the full stack is working. For a copy-paste version with assertions, see the test script in the repo's tests/ directory.