Reference
Every config field, command and endpoint.
Config file
spotagentiq.json. Values in token, slack_webhook and upstream env support ${ENV_VAR} expansion.
| Field | Default | Meaning |
|---|---|---|
agent | agent | Name shown in logs, the inbox and Slack. |
principal | The person the agent acts for, e.g. ops@acme.com. Recorded on every entry. | |
listen | Inbox address, e.g. :8484. Required if any rule (or the default) needs approval. | |
public_url | from listen | How people reach the inbox. Used in Slack links. |
token | $SPOTAGENTIQ_TOKEN | Inbox password. |
log_path | spotagentiq.audit.jsonl | Audit log file. |
approval_timeout | 10m | How long a held call waits. Go duration: 90s, 10m, 1h. |
default_action | allow | allow, require_approval or deny when no rule matches. |
slack_webhook | Incoming-webhook URL for held-call alerts. | |
upstreams[] | MCP servers to launch: name, command, args, env, cwd. At least one; names must be unique. | |
rules[] | See Policies. | |
redact[] | Argument keys masked in logs, inbox and Slack. Case-insensitive, any depth. |
Command line
| Command | What it does |
|---|---|
spotagentiq serve --config FILE | Run as an MCP server over stdio. This is what your MCP client launches. Logs go to stderr; stdout is the protocol. |
spotagentiq init | Print a starter config. |
spotagentiq verify --log FILE [--json] | Check the hash chain. Exit 0 if intact, 3 if not. |
spotagentiq export --log FILE | Write the log as CSV to stdout. |
spotagentiq demo [--listen :8484] | Guided demo with a fake tool server and scripted agent. |
spotagentiq version | Print the version. |
HTTP API
Served on listen. Every endpoint except /healthz needs Authorization: Bearer <token> (or ?token=).
| Endpoint | Returns |
|---|---|
GET /api/state | Pending calls, recent decisions, the last 100 log entries and chain status. |
POST /api/decide | Body {"id","decision":"approve"|"reject","approver","note"}. |
GET /api/log?limit=N | Raw log entries. |
GET /api/verify | Chain check result. |
GET /api/policy | The compiled rules. |
GET /export.csv?since=&until= | CSV export. Bounds are RFC 3339 timestamps. |
GET /healthz | Liveness. |
Approving from your own tooling, such as a chat bot or an on-call pager, is a POST /api/decide away.
curl -X POST -H "Authorization: Bearer $SPOTAGENTIQ_TOKEN" \
-d '{"id":"c_7f3a","decision":"approve","approver":"priya"}' \
http://localhost:8484/api/decideDocker
docker build -t spotagentiq .
docker run -p 8484:8484 -e SPOTAGENTIQ_TOKEN=... \
-v $PWD/spotagentiq.json:/etc/spotagentiq.json \
-v spotagentiq-audit:/var/lib/spotagentiq spotagentiqSpotAgentIQ launches upstreams as child processes, so the image needs whatever they need. The default image includes Node and Python, which covers npx and uvx servers. Put the inbox behind your VPN or a TLS reverse proxy.