Skip to content

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.

  1. Mint an API token.

    Settings → API tokens → Create. Name it quickstart, copy the value (starts with rc_…), and stash it in your shell:

    Terminal window
    export VONZIO_TOKEN="rc_…"
    export VONZIO_API="http://localhost:3000"
  2. 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.

  3. 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).

  4. 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.

  5. 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 or
    action. Use mail_search on INBOX with unseen=true and since set to
    yesterday's date, then mail_read_message on anything promising.
    Pick the top 3 by importance. For each, summarize in one sentence and
    include 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's
    nothing worth surfacing — don't send empty digests.

    Schedule: 0 13 * * 1-5 (8am EDT weekdays). notify_on: none — the agent handles delivery itself.

  6. Test it now.

    You can manually fire any playbook via REST:

    Terminal window
    PLAYBOOK_ID="pb_…" # from the playbooks list
    curl -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.

  • 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_user to 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).
  • Add Telegram thread-claim: configure playbook notifications with claim_thread=true so 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.