Quickstart
This walkthrough builds a tiny but real agent: a “morning briefing” that reads your inbox and summarizes anything that needs attention. It exercises authentication, profiles, integrations, and playbooks all at once.
It assumes a running instance at http://localhost:3000 (see Getting started). If you only want to send one message, that page is enough.
-
Mint an API token.
Settings → API tokens → Create. Name it
quickstart, copy the value (starts withrc_…), and stash it in your shell:Terminal window export VONZIO_TOKEN="rc_…"export VONZIO_API="http://localhost:3000" -
Confirm auth works.
Terminal window curl -sS -H "Authorization: Bearer $VONZIO_TOKEN" \"$VONZIO_API/v1/profiles" | jq '.[].slug'You should see your profile slugs. If you get 401, check the token; if the connection is refused, check the stack is up (
curl $VONZIO_API/health) and the port matches your install. -
Connect your mailbox.
Dashboard → Settings → Integrations → Mail → “Connect mailbox”. Pick your provider’s preset and enter your username and an app password. Vonzio verifies IMAP and SMTP before saving and keeps the credentials encrypted server-side. See Mail (IMAP/SMTP).
-
Scope the mailbox to your agent (optional but recommended).
Same row → “Scope: all agents” → switch to “Specific agents” → check only the agent that should see your inbox. Other agents won’t see
mail_*tools at all. See Integrations & scope. -
Schedule the morning briefing playbook.
Playbooks → New, pick your agent, and use this prompt:
Scheduled run (morning briefing, weekday mornings).Find emails from the last 24h that look like they need a response oraction. Use mail_search on INBOX with unseen=true and since set toyesterday's date, then mail_read_message on anything promising.Pick the top 3 by importance. For each, summarize in one sentence andinclude the sender and subject so I can find it later.Deliver the summary via mcp__notify__notify_user with channel="telegram"(or the channel you've configured). Skip the call entirely if there'snothing worth surfacing — don't send empty digests.Schedule:
0 13 * * 1-5(8am EDT weekdays).notify_on: none— the agent handles delivery itself. -
Test it now.
You can manually fire any playbook via REST:
Terminal window PLAYBOOK_ID="pb_…" # from the playbooks listcurl -sS -X POST -H "Authorization: Bearer $VONZIO_TOKEN" \"$VONZIO_API/v1/playbooks/$PLAYBOOK_ID/run"The agent will run in the background. Watch your configured channel.
What just happened
Section titled “What just happened”- The agent ran in a fresh Docker container with a clean filesystem.
- It got injected MCP servers based on your profile’s config —
memory,mail(because of the integration),notify,vonzio(platform operations). - The
mail_*tool calls logged in to your mailbox server-side with your stored credentials — the container never saw them. - The agent’s final response was delivered through
mcp__notify__notify_userto whichever channel you configured. - The session expired after completion (playbook sessions are ephemeral) — but you can still find it in your workspaces list if it qualifies (see Workspaces).
Where to go next
Section titled “Where to go next”- Add Telegram thread-claim: configure playbook notifications with
claim_thread=trueso your replies route back to the same agent context. See Telegram integration. - Custom tools: write a tool file and add it to your profile. See Tools, skills, subagents.
- The full API: REST and WebSocket reference.