Self-host Agent Inbox

Local evaluation

This command exposes SMTP on local port 2525, the API and PWA on 8080, and preserves messages in a named volume:

docker run --rm --pull=always \
  -p 2525:25 \
  -p 8080:8080 \
  -v agent-inbox-data:/data \
  -e DOMAIN=localhost \
  registry.agentics.dk/agentics/pks-agent-inbox:latest

Open http://localhost:8080. With no OIDC_ISSUER, the server runs in open mode; use that only on a trusted local network.

Production ports and storage

For real inbound email, publish TCP port 25 directly and put the HTTP surface behind TLS:

docker run -d \
  --name agent-inbox \
  --restart unless-stopped \
  -p 25:25 \
  -p 8080:8080 \
  -v agent-inbox-data:/data \
  -e DOMAIN=mail.example.com \
  registry.agentics.dk/agentics/pks-agent-inbox:latest

Pin a semver image tag instead of latest when deployments must be reproducible. Each release is published for Linux AMD64 and ARM64.

DNS

Create an A record for the server hostname and an MX record for every receiving domain:

mail.example.com.  A   <server-ip>
example.com.       MX  10 mail.example.com.

Allow inbound TCP port 25 in the host and provider firewalls. The service is receive-only and does not require outbound SMTP.

Identity

Set these variables to protect the PWA and human API with your OIDC provider:

OIDC_ISSUER=https://login.example.com/realms/example
OIDC_CLIENT_ID=agent-inbox
OIDC_CLIENT_SECRET=<secret>
PUBLIC_BASE_URL=https://inbox.example.com
SESSION_SECRET=<long-random-value>

Also register ${PUBLIC_BASE_URL}/auth/callback with the provider. Keep open mode for local evaluation only.

Operate the local data store

The image includes agent-inbox-cli, which works directly against /data:

docker exec agent-inbox agent-inbox-cli --data /data inboxes
docker exec agent-inbox agent-inbox-cli --data /data owner add team --domain mail.example.com

Back up the mounted volume. It contains the original messages, Markdown, attachments, routing configuration, sessions, and push configuration.