> ## Documentation Index > Fetch the complete documentation index at: https://docs.ziro-agent.com/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart > Install dependencies, run the first-run wizard, and hold your first conversation with a Ziro agent. 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](https://openrouter.ai/keys) is the default and gives you access to most models with one key. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -fsSL https://ziro-agent.com/install.sh | bash ``` On Windows: ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/installation) for what it does and how to configure it. Needs [uv](https://docs.astral.sh/uv/). From the repository root: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} python -m app.cli.startup ``` See [Installation](/installation) for exactly what this fetches. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ziro ``` With no arguments, `ziro` paints the terminal UI immediately and walks you through first-run setup before starting the engine. 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. 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. 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. 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](/interfaces/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. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} python -m app.cli.chat_once --user alice --message "Hello" ``` Pin a specific agent for the run: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/guides/permissions). ## Useful launch flags ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 # 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](/reference/cli). ## Next steps Dependency groups, storage modes, and where Ziro keeps its state. What actually happens between your message and the reply. The per-agent policy files and how to change behaviour.