CHP Quickstart

Synced from chp-core/docs/quickstart.md.

1. Install

pip install 'chp-core[signing]' chp-host

The [signing] extra pulls the ed25519 backend — you want it for anything beyond local experiments: serving a signed host, verifying bundles and provenance statements, issuing mandates. Plain pip install chp-core works too and stays at the hash-chain tier.

Adapters install the same way as you need them (pip install chp-adapter-http chp-adapter-filesystem chp-adapter-audit, …).

Then take the guided first run:

chp                 # prints the start-here path
chp serve-demo      # a governed demo host with a copy-pasteable first invoke

Contributors working from this repository can use editable installs (pip install -e packages/python packages/chp-host) or the full-node bootstrap scripts (scripts/bootstrap-mac.sh primary, scripts/bootstrap-linux.sh).

2. Declare And Invoke A Capability

from chp_core import LocalCapabilityHost, capability

host = LocalCapabilityHost("quickstart-host")

@capability(
    id="demo.greet",
    version="1.0.0",
    description="Return a greeting.",
)
def greet(ctx, name: str):
    ctx.emit("greeted", {"name": name})
    return {"message": f"Hello {name}"}

host.register(greet)

result = host.invoke(
    "demo.greet",
    {"name": "CHP"},
    correlation_id="quickstart-001",
)

print(result.data)          # {"message": "Hello CHP"}
print(result.evidence_ids)  # list of evidence event IDs

Use await host.ainvoke(...) inside an async event loop.

3. Serve A Host Over HTTP

# Profile mode (recommended)
chp-host serve --profile environments/profiles/mac-dev.json

# Adapter list mode
chp-host serve --adapters http,filesystem,audit --port 8803

# Check the host
curl http://localhost:8803/health
curl http://localhost:8803/capabilities | python3 -m json.tool | head -40

4. Use With Claude Desktop (MCP)

chp-host mcp exposes all CHP capabilities as MCP tools. Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "chp": {
      "command": "chp-host",
      "args": ["mcp", "--profile", "/Users/YOU/.chp/config/primary.json"]
    }
  }
}

Restart Claude Desktop. Every tool call is wrapped in CHP evidence.

See docs/claude-desktop-mcp.md for the full setup guide including multi-host mesh mode and persistent evidence stores.

5. Set Up A Persistent Node

# One command from zero to a boot-persistent service
chp-host init --role primary --yes

# Check it started
chp-host status
curl http://localhost:8803/health

6. Mesh Multiple Nodes

# On the primary — generate an invite key for a worker
chp-host mesh invite --role worker

# On the worker — run init with the key from the invite
chp-host secrets set CHP_HOST_API_KEY    # enter the key from above
chp-host init --role worker --yes

# Back on primary — register the worker
chp-host mesh add http://<worker-ip>:8803
chp-host mesh list                        # ✓ OK
chp-host gateway                          # zero-arg: reads ~/.chp/mesh.json

7. Query Evidence

# Via adapter (requires audit adapter)
chp-host mcp --adapters audit
# Then invoke: chp.adapters.audit.query {"capability_id": "chp.adapters.http.request"}

# Direct SQLite
sqlite3 ~/.chp/mac.sqlite \
  "SELECT capability_id, outcome, started_at FROM invocations ORDER BY started_at DESC LIMIT 10;"

8. Run Conformance

python -m pytest packages/python/tests/ packages/chp-host/tests/ -q --no-cov