Commands and configuration for the remote Agent Inbox CLI.
agent-inbox <command>agent-inbox is the remote client for the hosted or self-hosted Agent Inbox HTTP API.
agent-inbox login
agent-inbox inboxes
agent-inbox webhooks list --inbox <owner/domain|id>
agent-inbox webhooks add --inbox <owner/domain|id> --url URL [--match PATTERN]
agent-inbox webhooks rm --inbox <owner/domain|id> <webhookId>
agent-inbox webhooks test --inbox <owner/domain|id> <webhookId>
agent-inbox version
agent-inbox new [--label s] [--ttl 24h|7d] [--allow pat]... [--prefix s] [--domain d] [--keep] [--pair] [--json]
agent-inbox wait [--timeout 10m] [--from s] [--subject re] [--json] [--no-mark] [--new-only]
agent-inbox emails [--unread] [--limit n] [--json]
agent-inbox read <id> [--json] [--raw] [--no-mark]
agent-inbox attachment <id> <name> [-o path]
agent-inbox allow [ls|add|rm] [pattern]
agent-inbox mailboxes [--json]
agent-inbox extend --ttl 24h|7d [address]
agent-inbox keep [address]
agent-inbox rm [address]
agent-inbox mcp [--mailbox a]
agent-inbox channel [--mailbox a]
agent-inbox init [--agent claude|codex|cursor|all] [--channel] [--skill] [--force]
agent-inbox skill
Every mailbox command accepts --mailbox <address>. The default is $AGENT_INBOX_MAILBOX, otherwise the newest active mailbox.
| Command | What it does |
|---|---|
new | Gets an address. Logged in: created directly. Otherwise on a public domain: created at once with no login (at most 72h, not kept). Otherwise prints a pairing code and link for a human to approve. --pair forces pairing. |
wait | Prints the oldest unread matching message, or blocks until one arrives, and marks it read. --from matches sender text, --subject is a regular expression, --new-only ignores mail already waiting. |
emails, read | List mail and read one message. Bodies are framed as untrusted. --raw streams the RFC 822 message. |
attachment | Downloads an attachment to ./<name> or -o path. |
allow | Shows or changes the sender allow-list. add and rm need the human to have allowed the agent to edit it, or an owner login on this machine. |
mailboxes | Lists local mailboxes and their state. |
extend, keep | Change the lifetime or make the address permanent. Need the owner's login. Not available on public no-login mailboxes. |
rm | Gives the address up. The mailbox token is enough. Its mail is deleted. |
mcp | Runs a stdio MCP server for the mailbox, with inbox_whoami and inbox_wait_for_email. |
channel | Runs a Claude Code channel that wakes the session on new mail. |
init | Registers the MCP server for an agent. --skill writes .claude/skills/agent-inbox/SKILL.md. No token is written to config. |
skill | Prints the agent skill. |
Allow-list entries: ann@example.com, *@github.com, *@*.example.com, *@* (any sender that passes DMARC alignment), and * (anyone, authentication not checked).
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error |
| 2 | wait timed out; or wrong usage with no command |
| 3 | Pairing was denied by the human |
| 4 | Pairing request expired |
| 5 | Pairing request already claimed |
--match accepts *, an exact local part such as orders, or a prefix such as support-*.
| Variable | Default | Purpose |
|---|---|---|
AGENT_INBOX_SERVER | https://inbox.agentics.dk | Inbox API base URL |
AGENT_INBOX_MAILBOX | newest active | Mailbox address used by mailbox commands |
AGENT_INBOX_CLIENT | agent-inbox | Client name shown to the human when pairing |
AGENT_INBOX_ISSUER | Agentics realm | OIDC issuer |
AGENT_INBOX_CLIENT_ID | agentics-inbox-desktop | OIDC public client |
AGENT_INBOX_HOME | ~/.agent-inbox | Credential and configuration directory |
USE_ASPIRE | unset | Use the local Aspire credential home when set to 1, true, yes, or on |
To target a self-hosted instance:
AGENT_INBOX_SERVER=https://inbox.example.com agent-inbox login
The selected server, issuer, and client ID are retained with the login. Environment variables override retained values.
The secret returned by webhooks add is displayed once. A receiver must calculate HMAC-SHA256 over the raw body and compare it with:
X-Inbox-Signature: sha256=<hex-digest>
Use webhooks test to validate connectivity and signature handling before relying on live email events.