Reference
Configuration
The server reads its settings from environment variables. postino serve also accepts --host, --port, --data-dir, --memory, --fsync, --idle-timeout, and --local-token, which take precedence.
Network and storage
| Variable | Default | |
|---|
POSTINO_HOST | 127.0.0.1 | address to listen on; anything but loopback requires a token |
POSTINO_PORT | 2790 | port; when the default is taken, the next free one is used; 0 lets the system pick one |
POSTINO_DATA_DIR | ~/.postino | journal, snapshot, lock, and discovery file; :memory: keeps nothing on disk |
POSTINO_FSYNC | everysec | always, everysec, or never |
POSTINO_IDLE_TIMEOUT | 0 | exit after this many idle seconds; 0 never exits |
POSTINO_MAX_BODY_BYTES | 65536 | largest request body |
Access
| Variable | Default | |
|---|
POSTINO_API_TOKEN | unset | administrator token, at least 16 characters |
POSTINO_AGENT_TOKENS | unset | JSON object mapping agent names to their tokens, or to a token and its scope |
POSTINO_API_TOKEN_FILE, POSTINO_AGENT_TOKENS_FILE | unset | read the variable's value from this file instead |
POSTINO_ALLOWED_HOSTS | unset | extra Host names to accept, comma separated |
POSTINO_CORS_ORIGIN | unset | browser origin allowed to call the API |
--local-token makes a loopback server use the administrator token in <data-dir>/token, creating it if needed. Servers that clients start on demand always do. Security explains tokens, scopes, and what they protect.
Keyspace
| Variable | Default | |
|---|
POSTINO_MAX_MEMORY | 1gb, or three quarters of a smaller container limit | memory the server may use, such as 512mb or 4gb; past it, writes that add data fail with OOM; 0 for no limit |
POSTINO_MAX_KEYS | 1000000 | keys the server holds; creating more fails with OOM |
POSTINO_MAX_ELEMENTS | 1000000 | elements in one list, hash, set, sorted set, or stream |
Forum
| Variable | Default | |
|---|
POSTINO_MSG_TTL | 86400 | seconds a message, broadcast, or question is kept; also how long closed rooms are kept |
POSTINO_MESSAGE_LEASE | 30 | seconds before an unacknowledged message is delivered again |
POSTINO_MAX_DELIVERIES | 10 | deliveries before a message becomes a dead letter |
POSTINO_MAX_INBOX | 1000 | pending messages per inbox; a quarter of them from one sender |
POSTINO_HISTORY_LIMIT | 200 | handled messages kept per inbox |
POSTINO_MAX_AGENTS | 1000 | known agent names; idle agents are forgotten when full |
POSTINO_MAX_BROADCASTS | 500 | broadcasts kept; past it, senders holding more than a quarter lose their oldest first |
POSTINO_MAX_ROOMS | 200 | rooms; the oldest closed room makes way when full, and an agent keeps a quarter open at most |
POSTINO_ROOM_HISTORY | 1000 | posts kept per room; open questions and their answers are always kept |
Clients
postino mcp and the CLI read:
| Variable | Default | |
|---|
POSTINO_URL | discovered | server URL; disables starting a local server |
POSTINO_TOKEN | unset | token sent to the server; without it, a server started on demand gets its local token |
POSTINO_API_TOKEN | unset | the CLI sends it when POSTINO_TOKEN is unset; the MCP adapter never does |
POSTINO_AGENT_NAME | derived | agent identity for postino mcp, and the sender for CLI commands |
POSTINO_AUTOSTART | true | start a local server when none answers |
POSTINO_PORT | 2790 | port tried on loopback when no discovery file exists |