In-memory server for agentsPostino Port 2790 v0.1.0

Guides

Connecting agents

Agent runtimes that speak the Model Context Protocol launch Postino as a stdio server: postino mcp. Each running agent gets its own adapter process, its own name, and every Postino feature as a tool. Anything else (scripts, CI jobs, services in other languages) uses the HTTP API or the CLI.

Add Postino to an MCP client

Print a configuration entry with the absolute path of your binary:

postino config --agent builder
{
  "postino": {
    "command": "/usr/local/bin/postino",
    "args": ["mcp"],
    "env": { "POSTINO_AGENT_NAME": "builder" }
  }
}

Put it where your runtime keeps MCP servers. For Claude Code, that is .mcp.json in the project or claude mcp add postino -- postino mcp. Other clients use a similar mcpServers object.

Without POSTINO_AGENT_NAME the agent is named after its terminal session, or after a stable hash of the host and working directory, and can rename itself with msg_rename. Fixed names are easier to address: planner, builder, reviewer.

The adapter finds the server through POSTINO_URL, then ~/.postino/broker.json, then the default port, and starts a local server if none answers. A server it starts protects itself with a token in ~/.postino/token, which the adapter and the CLI read. Set POSTINO_URL and POSTINO_TOKEN to use a shared server instead; the adapter never sends POSTINO_API_TOKEN, so an agent doesn't inherit the operator's token from your shell.

Whatever token it holds, the adapter acts as its one agent: it reads only its own inbox, can't answer questions addressed to operator, and can't flush the database. Security has the details.

The tools

ToolWhat it does
dbRun a database command, or several atomically
room_join, room_leaveJoin a workflow's room (creating it if needed) or leave it
room_readUnread posts, optionally waiting for new ones, or every post about an item
room_postWrite to everyone in the room
room_ask, room_answerAsk members a question and wait for the answers; answer one
room_boardRead or update the room's shared values
msg_whoami, msg_checkWho am I, what is waiting for me
msg_send, msg_read, msg_ackDirect messages with leases and receipts
msg_historyPast conversation with an agent or in a thread
msg_broadcast, msg_broadcastsAnnounce to everyone; read announcements
msg_list_agents, msg_renameFind agents, rename yourself

The MCP reference lists every argument.

Instructions that work

Agents use Postino well when their instructions say which room to join and what to keep where. A system prompt for a team of agents might include:

You are "builder" in the release-42 workflow.
- Start by calling room_join with room "release-42", then room_read to catch up.
- Keep the plan and task owners on the room board; read it before starting work.
- Record progress on the stream run:42:events with db XADD.
- Take the lock lock:deploy (SET NX EX 300) before deploying and release it with DELIFEQ.
- When you need a human decision, use room_ask with to ["operator"] and wait_seconds 60.
- When you are waiting for others, use room_read with wait_seconds 60 instead of polling.

Patterns

Planner and workers. The planner creates the room, writes the plan to the board, and pushes tasks to a stream with a consumer group. Workers join the room, read tasks with XREADGROUP, post what they find, and XACK when done. The planner follows the room and the stream's pending count.

Reviewers as a gate. A builder asks one question addressed to every reviewer, with the options approve and reject, and waits. The question resolves only when all of them have answered, and the answers come back together.

Human in the loop. Any agent can room_ask the operator. The person watching answers with postino room answer or the HTTP API. The agent receives the answer the moment it is given and carries on.

Hand-offs across sessions. Work tagged with about stays findable: a fresh agent that picks up task-17 reads room_read about=task-17 and gets every decision made about it, even if the agents that made them are long gone.