Skip to content

Getting started

Install vonzio on macOS or Linux with the one-line installer (it checks for Docker and Compose, generates a .env with fresh secrets, and starts the stack):

Terminal window
curl -fsSL https://raw.githubusercontent.com/vonzio/vonzio/main/install.sh | bash

When it finishes, open http://localhost:3000 — the dashboard and the API are served from the same port. See the repo’s self-hosting guide for options and troubleshooting.

Before clicking around, internalize this:

You ─ have many ─→ Agent profiles
│
│ each one runs in
▼
Workspaces ─ live in ─→ Docker containers
│
│ talk to
▼
MCP servers (memory, notify, mail, calendar, vonzio)
Tools (Bash, Read, Write, custom)
Integrations (Slack, Telegram, Mail, Calendar, Email, Webhook)

Read Architecture for the long version. The list below is the minimum to go from zero to a working agent.

  1. Create the admin account.

    The first visit lands on /setup. Enter a name, email, and password — this creates the instance’s admin account and signs you in. There is no external sign-up; the account lives in your own database.

  2. Connect a model provider.

    Onboarding asks for a provider (Anthropic API key, Claude subscription, ChatGPT subscription, Ollama Cloud, or any OpenAI-compatible endpoint) and a default model. You can change keys later under Settings → Keys. Agent traffic goes straight to that provider — your key, your spend.

  3. (Optional) Create another agent.

    Setup gives you a default agent. For more, go to Agents → New agent. Pick a model, give it a slug (coding, research, etc.), and accept the defaults for now. The slug is how you’ll address it in chat (@coding) and in API calls.

  4. Send a message.

    Open Workspace, pick your agent from the dropdown, type a message, hit send. The agent runs in a fresh Docker container, streams tokens back over WebSocket, and ends the turn when it has nothing more to say.

  5. (Optional) Connect an integration.

    Settings → Integrations. Slack and Telegram give you a chat surface outside the dashboard. Mail (IMAP/SMTP) and Calendar (CalDAV) give the agent access to your inbox and calendar. See Integrations overview.

  6. (Optional) Schedule a playbook.

    Playbooks → New. A playbook is a scheduled prompt that runs autonomously on cron. Pair with notifications and you’ve got a proactive agent. See Playbooks.

  • Quickstart — concrete walkthrough that ends with a working agent doing something useful
  • Architecture — the mental model. Don’t skip if you plan to use the API.
  • API authentication — how to mint a token for CLI / scripts / agents