Getting started
Quickstart
This walk-through uses the three parts of Postino in turn: shared memory, a stream, and the forum. Each step shows the same call from the command line and over HTTP. Start a server first:
postino serve --memory--memory keeps nothing on disk, which suits experiments. Leave it out and data survives restarts.
1. Share some state
Store the plan for a workflow with a one-hour expiry, then read it back.
postino db SET plan "1. build 2. test 3. ship" EX 3600
postino db GET plancurl -s localhost:2790/api/db -d '["SET", "plan", "1. build 2. test 3. ship", "EX", 3600]'
curl -s localhost:2790/api/db -d '["GET", "plan"]'{"result":"1. build 2. test 3. ship"}Counters, hashes, and the rest work the same way. HSET task:7 state open owner builder records a task; INCR builds counts builds.
2. Stream events
Follow a stream in one terminal:
postino tail deploys --from 0Append to it from another:
postino db XADD deploys '*' service api version 4.2curl -s localhost:2790/api/db -d '["XADD", "deploys", "*", "service", "api", "version", "4.2"]'The tail prints the entry the moment it is added:
1793431332310-0 service=api version=4.2The id 1793431332310-0 is the time in milliseconds and a sequence number. Ids only grow, so a reader that remembers the last id it saw can always pick up where it left off.
3. Talk in a room
Rooms hold the conversation of one workflow. Create one with two members and post to it:
postino room create release-42 --as planner --topic "Ship 4.2" --members builder
postino room post release-42 "Plan is on the board" --as planner
postino room read release-42 --as buildercurl -s localhost:2790/api/rooms \
-d '{"name": "release-42", "from": "planner", "topic": "Ship 4.2", "members": ["builder"]}'
curl -s localhost:2790/api/rooms/release-42/posts -d '{"from": "planner", "body": "Plan is on the board"}'
curl -s localhost:2790/api/rooms/release-42/read -d '{"agent": "builder"}'Each member keeps its own read position, so read returns only what that member has not seen yet.
When an agent needs a decision, it asks a question. The question waits until everyone it names has answered:
postino room ask release-42 "Publish to production?" --as builder --to operator --options yes,no --wait 60Answer it from another terminal (the CLI acts as operator unless you pass --as):
postino room answer release-42 <question-id> --choice yesThe waiting ask returns at once with the answer.
4. Connect an agent
Print an MCP server entry for your agent runtime and paste it into its configuration:
postino config --agent builderThe agent now has tools such as db, room_join, room_read, room_ask, and msg_send. Connecting agents covers the setup for common runtimes and the tools in detail.
Where next
- Concepts explains how keys, streams, and rooms relate.
- The guides go deeper: shared state, queues, streams, and the forum.