bot-marshal documentation

Start here if you are new; each page below stands on its own once you have.

Getting started

• Getting started — install it, write a minimal config, generate a CA, put a request through it. Fifteen minutes, no agent required.
• Concepts — the model the rest of the documentation assumes: how a request travels from capture through identity, the policy chain, and transforms, and where default-deny actually lives.

Practical guides

• Read-only GitHub API access — allow reads, refuse write methods, and inspect the policy decisions with curl.

Find a feature

I want to…	Start here
Permit reads but refuse unwanted writes	Request rules
Use API keys without giving them to an agent	Secret injection and provider examples
Capture a CLI login and renew tokens	OAuth workflows and bootstrap walkthrough
Choose models and providers centrally	LLM routing
Restrict tools and their arguments	MCP tool controls
Detect credentials in outgoing requests	DLP scanning
Give each agent its own access and enforce routing	Identity and Linux containment
Use native decision models to judge or route requests	Decision APIs
Judge requests with an LLM	AI judge
Investigate a decision or roll out a policy gradually	Audit log and warn mode
Set or filter request headers	Header transforms
Limit response bodies	Response size limits
Check service health or reload policy	Management API and reload
Understand streaming and buffering costs	Streaming

Reference

• CLI — every subcommand and global flag.
• Configuration — the config file, and how it splits across profiles/, bundles/ and transforms/ directories.
  • Profiles — the unit of policy; embedded vs named.
  • Policy layers — denylist, allowlist, rules, dlp, mcp, judge.
  • Bundles — named, reusable allow-lists.
  • Transforms — header filtering, secret injection, response rewriting.
  • Bind groups — shared sandbox filesystem access.
  • LLM routing — model aliases and dialect translation.
  • Decision APIs — native judge providers and agent routing.
  • OAuth2 credentials — enrolment, capture and token lifecycle.
  • Secret injection examples — provider cookbook.
  • Identity — which agent is connecting, and marshal run.

Running it

• Capture — explicit proxy ingress, DNS resolver limitations and upstream checks.

• Observability — logs, the audit trail, and what to watch.

• Operations — the management API, hot reload, and rolling default-deny out with warn mode.

• Production — running as a dedicated service user under systemd.

• Troubleshooting — startup, trust, attribution, policy and OAuth failures.

Project

• Roadmap — what is built, what is deliberately not, and why.
• Architecture decisions — why the design is the way it is: the constraints that forced each significant choice, and the alternatives rejected.