User Guides

Quickstart

Get tagent (trusty-agents) running in five minutes.

1. Install

trusty-agents is not published to crates.io — build it from the trusty-tools monorepo source.

git clone https://github.com/bobmatnyc/trusty-tools
cd trusty-tools
cargo install --path crates/trusty-agents --locked
# Binary: ~/.cargo/bin/tagent

On macOS, prefer the signed-install script — it also signs the Trusty Agents.app desktop shell if present, so both artifacts keep their TCC grants across rebuilds:

scripts/install-trusty-agents-signed.sh
# or: make install-agents-signed

2. Configure credentials

Create .env.local in your working directory (never committed):

cat > .env.local <<'EOF'
OPENROUTER_API_KEY=sk-or-v1-...
# Optional: direct Anthropic API
# ANTHROPIC_API_KEY=sk-ant-api03-...
# Optional: enables web_search tool
# BRAVE_API_KEY=BSA...
EOF

You only need one LLM credential to get started. OPENROUTER_API_KEY covers every bundled agent. See configuration.md for the full credential matrix.

3. Verify

tagent --version
# trusty-agents v0.38.6 build #1

4. Run modes

Interactive CTRL REPL (default)

tagent
# or explicitly:
tagent --ctrl

You get a prompt:

CTRL> Write a Python script that formats CSV as a markdown table

CTRL routes the request to a per-project PM, which delegates to the right sub-agent (e.g. python-engineer). Type /help for slash commands.

API server + Web UI

tagent --api --port 7654
# [trusty-agents] API:    http://localhost:7654/api
# [trusty-agents] Web UI: http://localhost:7654/
# [trusty-agents] Docs index: 24 documents indexed from ./docs

The web UI is embedded in the binary — no separate frontend deploy. Add --api-token <TOK> to require bearer-token auth on /api/* routes.

Workflow mode

Run a declarative pipeline (research → plan → code → qa → observe):

tagent --workflow prescriptive \
  --task "Implement FizzBuzz with pytest tests" \
  --out-dir ./out/fizzbuzz

Generated files land under --out-dir and pytest runs automatically in the qa phase.

Direct mode (bypass PM)

tagent --direct python-engineer \
  --task "Bubble sort with type hints" \
  --out-dir ./out/sort

Useful for scripting or iterating on a single agent.

5. Search project docs from CTRL

CTRL ships with a search_docs tool backed by an in-memory TF-IDF index. Just ask in natural language:

CTRL> how do I write a custom skill?

CTRL will call search_docs("write custom skill") and answer using the matching files under docs/. The same index powers GET /api/docs/search?q=... on the API server.

Next steps

CLI reference — every flag, every mode
Configuration — .trusty-agents/, agents, skills, workflows
Agents and skills — what's bundled, how to extend