treeship

name

treeship

description

Create cryptographically signed, portable trust receipts for AI agent workflows using Treeship.dev. Use when the user wants to sign agent actions, create verifiable receipts, wrap commands with attestations, verify artifact chains, push artifacts to the Treeship Hub, manage approval-gated actions, or integrate Treeship into their agent workflow. Covers the Treeship CLI (treeship), Python SDK (treeship-sdk), TypeScript SDK (@treeship/sdk), MCP bridge (@treeship/mcp), and Hub API (api.treeship.dev). Trigger on any mention of attestation, verifiable receipts, signed receipts, agent trust, Treeship, action signing, cryptographic proof of agent work, portable receipts, approval workflows, session receipts, Merkle proofs, decision cards, or coverage levels.

Treeship — Portable Trust Receipts for Agent Workflows

Local-first. Cryptographically verifiable. Works offline. Ed25519 signatures. SHA-256 content hashing. Merkle proofs. The receipt is yours, not ours.

Quick Start

# Install Treeship
curl -fsSL treeship.dev/setup | sh

# Core loop
treeship wrap -- npm test        # sign what happened
treeship verify last             # verify offline
treeship hub push last           # share verify URL

When to Use Treeship

• Sign agent actions — tamper-proof receipts of what an agent did
• Verify workflows — cryptographically verify chains of actions
• Audit agent work — evidence, not chat logs
• Gate sensitive actions — human approval before execution
• Hand off between agents — cryptographically signed transitions
• Share verification URLs — publish to treeship.dev
• Comply with requirements — auditable proof of behavior

Installation

# One-liner (setup + init + instrument)
curl -fsSL treeship.dev/setup | sh

# Step by step
curl -fsSL treeship.dev/install | sh
treeship init
treeship setup

# Python SDK
pip install treeship-sdk

# TypeScript SDK
npm install -g treeship
npm install @treeship/sdk
npm install @treeship/mcp

Core CLI Commands

treeship wrap -- <command>              # wrap with signed receipt
treeship verify <id>                    # verify chain
treeship verify last                    # verify most recent
treeship session start --name "..."     # start session
treeship session close                  # close session
treeship session report                 # upload receipt
treeship hub push last                  # push to Hub
treeship approve --approver human://... # create approval
treeship wrap --approval-nonce <n> --   # use approval
treeship init                           # keypair generation
treeship key show                       # show public key
treeship inspect <id>                   # inspect artifact
treeship doctor                         # check workspace
treeship ui                             # TUI dashboard
treeship setup                          # guided first-run
treeship add --discover                 # discover agents
treeship harness list                   # list harnesses
treeship harness inspect <id>           # inspect harness
treeship harness smoke <id>             # smoke test
treeship trust list                     # list pinned issuers (v0.10.3+)
treeship trust add <key_id> <pubkey> --kind <hub_checkpoint|ship|agent_cert>
treeship trust remove <key_id>

Note (v0.10.3+): Hub-checkpoint and agent-certificate verification require the embedded public key to match a configured trust root. After importing artifacts produced by a different ship/hub, expect treeship verify to fail with "untrusted issuer" until the issuer is pinned via treeship trust add. Pre-v0.10.3 the verifier trusted the embedded key, which made self-signed forgeries pass; the new gate closes that.

Actor URIs

• agent://<name> — AI agent
• human://<name> — Human operator
• agent://ci-pipeline — CI/CD system

Statement Types

Type	Purpose	Method
treeship/action/v1	Agent did something	attest_action() / wrap
treeship/approval/v1	Someone approved	attest_approval() / approve
treeship/handoff/v1	Work moved between agents	attest_handoff()
treeship/decision/v1	LLM made a decision	attest_decision()
treeship/use/v1	Approval consumed	auto (v0.9.9+)

Python SDK

from treeship_sdk import Treeship

ts = Treeship()

# Attest action
result = ts.attest_action(
    actor="agent://my-agent",
    action="tool.call",
    parent_id="art_abc123",
    approval_nonce="nonce_xyz",
    meta={"tool": "read_file", "path": "src/main.rs"}
)
print(result.artifact_id)  # art_...

# Attest approval
approval = ts.attest_approval(
    approver="human://alice",
    description="approve deployment",
    expires_in=3600
)
print(approval.artifact_id, approval.nonce)

# Verify
verified = ts.verify(result.artifact_id)
# verified.outcome: "pass" | "fail" | "error"
# verified.chain: number of linked artifacts

# Push to Hub
push = ts.dock_push(result.artifact_id)
# push.hub_url: https://treeship.dev/verify/art_xxx

# Wrap command
result = ts.wrap("npm test", actor="agent://ci")

# Session report
report = ts.session_report()
# report.receipt_url: permanent public URL

TypeScript SDK

import { Ship } from "@treeship/sdk";

const ship = await Ship.init("./.treeship", "agent://my-agent");

const { receipt } = ship.attestAction({
  actor: { type: "agent", id: "agent://my-agent" },
  actionType: "tool.call",
  actionName: "search.web",
  inputs: JSON.stringify({ query: "AI safety" }),
  outputs: JSON.stringify({ results: ["paper1"] }),
});

ship.attestHandoff({
  fromActor: { type: "agent", id: "agent://researcher" },
  toActor: { type: "agent", id: "agent://writer" },
  taskCommitment: "complete-report",
});

ship.createCheckpoint();
const bundle = ship.createBundle("Workflow");
await ship.save();

Approval-Gated Actions

# 1. Human creates approval
approval = ts.attest_approval(
    approver="human://alice",
    description="approve payment up to $500",
    expires_in=3600
)

# 2. Agent uses approval nonce
result = ts.attest_action(
    actor="agent://executor",
    action="stripe.charge.create",
    approval_nonce=approval.nonce,
    meta={"amount": 299.00}
)

# 3. Verify (checks replay levels)
verified = ts.verify(result.artifact_id)

Chained Workflow

prev_id = None
for step in [
    {"actor": "agent://researcher", "action": "search.web"},
    {"actor": "agent://analyst", "action": "analyze.data"},
    {"actor": "agent://writer", "action": "generate.report"},
]:
    result = ts.attest_action(
        actor=step["actor"],
        action=step["action"],
        parent_id=prev_id
    )
    prev_id = result.artifact_id

result = ts.verify(prev_id)
print(f"Chain: {result.outcome}, {result.chain} steps")

MCP Bridge

For agents with MCP support, add Treeship as an MCP server:

# Claude Code
claude mcp add --transport stdio treeship -- npx -y @treeship/mcp

# Kimi Code CLI
kimi mcp add --transport stdio treeship -- npx -y @treeship/mcp

# Cursor
# Add to ~/.cursor/mcp.json:
{
  "mcpServers": {
    "treeship": {
      "command": "npx",
      "args": ["-y", "@treeship/mcp"]
    }
  }
}

Hub API

• Base: https://api.treeship.dev/v1/
• Auth: DPoP (no API keys)
• POST /v1/artifacts — push artifact
• GET /v1/verify/:id — public verification (no auth)
• PUT /v1/receipt/{session_id} — upload session receipt
• GET /v1/merkle/:id — Merkle inclusion proof

Public URLs: https://treeship.dev/verify/{artifact_id}

Result Types

ActionResult(artifact_id: str)
ApprovalResult(artifact_id: str, nonce: str)
VerifyResult(outcome: str, chain: int, target: str)
PushResult(hub_url: str, rekor_index: Optional[int])
SessionReportResult(session_id, receipt_url, agents, events)

All methods raise TreeshipError on failure.

Environment Variables

Variable	Purpose
TREESHIP_API_KEY	Hub API key (optional)
TREESHIP_AGENT	Default agent slug
TREESHIP_HUB_ID	Hub workspace ID

Key Files

• ~/.treeship/ — config, keys, local receipt store
• ~/.treeship/sessions/ — session packages
• .treeship/ — project-local ship

Standards

• Ed25519 (RFC 8032) — signatures
• DSSE — envelope format (Sigstore/in-toto compatible)
• SHA-256 — content addressing + Merkle tree
• RFC 8785 — JSON canonicalization

Resources

• Docs: https://docs.treeship.dev
• Hub: https://treeship.dev
• GitHub: https://github.com/zerkerlabs/treeship