Quickstart

This page takes you from nothing to a working chat session. You need Python 3.12+ and an API key from a model provider. openrouter.ai/keys is the default and gives you access to most models with one key.

Install Ziro

Install script
Source checkout

curl -fsSL https://ziro-agent.com/install.sh | bash

On Windows:

iwr -useb https://ziro-agent.com/install.ps1 | iex

The script needs only Python 3.11.9 or newer. It creates an isolated environment and puts ziro on your PATH. See Installation for what it does and how to configure it.

Needs uv. From the repository root:

uv sync

Either path installs the runtime and the local guardrail backends (Presidio PII detection and Llama Guard content safety). Neither downloads the models those backends use. That is the optional step below.

Optional but recommended before your first launch: pre-cache the local models so the first run does not stall on downloads.

python -m app.cli.startup

See Installation for exactly what this fetches.

Run ziro

ziro

With no arguments, ziro paints the terminal UI immediately and walks you through first-run setup before starting the engine.

Complete the setup wizard

The wizard runs as a full-screen page in the TUI. It asks for the following, in order:

Section	What it wants	Required
API key	Your provider key, validated before it is saved	Yes
Model	The model id to use by default, picked from the provider’s live catalog	No
Theme	`ziro` (the default), `carbon`, `nord`, or `gruvbox`	No
Advanced	Langfuse observability keys and `DATABASE_URL`	No

Press Esc to skip an optional section. Once the key is saved you can press Ctrl+A to skip everything remaining and go straight to chat.The wizard writes to ~/.ziro/.env. Re-open it at any time with ziro setup, the fields come back prefilled.

You only see the wizard when no API key is configured. On later launches Ziro goes straight to the pickers.

Work through the pickers

After the wizard, Ziro asks only for what it cannot resolve on its own. Each step is skipped when the answer is obvious:

Picker	Shown when
User	No `--user` flag and no remembered last user
Flavour	Unresolved and two or more flavours are configured
Thread	This user has existing threads in the active flavour
Agent	You are starting a new thread and the flavour has two or more enabled agents

A user keeps its own memories and threads. A flavour scopes which agents and threads you see and which memory store they share. The bundled set is chat, engineering, research, or safe. A thread is one conversation, resumable later. An agent is the persona and tool policy that runs the turn.The thread picker always offers a + New thread row. Pick it, or pick an existing thread to resume where you left off.

Send your first message

Type into the input box and press Enter. The turn streams live: reasoning first (collapsing to a one-line summary when it finishes), then any tool calls inline, then the answer rendered as Markdown.You can type before the engine has finished building. Anything you submit early is queued and runs in order once the runtime is ready. The footer shows starting…, then warming model, then connecting MCP, then clears.Try asking the agent to remember something about you, then start a new thread and ask about it, because long-term memory persists per user and flavour, independent of the thread.

Try a few slash commands

Slash commands are dispatched in the driver loop before the model runs. They cost no tokens and never touch the transcript.

Command	What it does
`/help`	List every command grouped by category
`/agent`	List agents in the active flavour, or switch to one
`/model`	List the active provider’s catalog, or switch model
`/new`	Start a fresh thread (`Ctrl`+`N` in the TUI)

A few more worth knowing early: /thread lists and resumes conversations, /settings re-opens the settings screen, /skills shows what the agent can reach, /stop aborts the turn in flight, and /quit exits.The full list is on Slash commands.

Try it headless

The same runtime answers a single prompt and exits, which suits scripts, cron jobs, and driving Ziro from another program. Headless runs never open the wizard or the pickers; they resolve --user (or the last remembered user) and fail fast with a clear message if nothing is configured.

python -m app.main --user alice -p "Summarize what you remember about me"

That prints the reply text and nothing else. Add --json for a machine-readable line instead:

python -m app.main --user alice -p "Summarize what you remember about me" --json

chat_once is the dedicated single-shot entry point with the same JSON contract:

python -m app.cli.chat_once --user alice --message "Hello"

Pin a specific agent for the run:

python -m app.cli.chat_once --user alice --agent researcher --message "Hello"

Headless runs are fail-closed on human-in-the-loop gates. A tool call that would raise an approval prompt is auto-denied instead of hanging, so a scripted run never blocks waiting for a human. Plan permissions accordingly. See Permissions.

Useful launch flags

python -m app.main --user alice --agent researcher    # start with a specific agent
python -m app.main --user alice --flavour research    # scope to a flavour
python -m app.main --user alice --thread <THREAD_ID>  # resume a conversation
python -m app.main --user alice --no-tui              # plain rich REPL instead of the TUI

The full flag surface is on the CLI reference.

Next steps

Installation

Dependency groups, storage modes, and where Ziro keeps its state.

Architecture

What actually happens between your message and the reply.

Configuration

The per-agent policy files and how to change behaviour.

Getting started

Concepts

Interfaces

Guides

Try it headless

Useful launch flags

Next steps

Installation

Architecture

Configuration

​Try it headless

​Useful launch flags

​Next steps

Installation

Architecture

Configuration

Try it headless

Useful launch flags

Next steps