Installation

Prerequisites

Requirement	Needed for	Notes
Python 3.12+	Everything	The runtime targets 3.12 and above
uv	Dependency install	Drives the workspace and its optional groups
A model provider API key	Every model call	OpenRouter, Anthropic, OpenAI, or a custom endpoint
Docker	Optional	PostgreSQL + pgvector, SearXNG, and the PDF sandbox image

Choose an install path

Install script
pip

The recommended way in. The script creates an isolated environment under ~/.ziro/versions/<version>, installs Ziro into it, and puts a ziro command on your PATH. It needs nothing but Python 3.11.9 or newer: no pipx, no uv, no admin rights.

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

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

Run ziro when it finishes. The first launch walks you through setup.

Piping a script from the internet into a shell is worth being careful about. Read it first: both are served as plain text over HTTPS at ziro-agent.com/install.sh and ziro-agent.com/install.ps1.

Both scripts accept the same options:

Option	Effect
`--version <v>`	Install a specific version instead of the latest
`--uninstall`	Remove the environment and the shims. Your settings and data are kept
`--help`	Print usage (`Get-Help` on the PowerShell script)

Configuration is by environment variable, so the options survive being piped to a shell: ZIRO_HOME, ZIRO_BIN_DIR, ZIRO_VERSION, ZIRO_PYTHON, ZIRO_INDEX_URL, ZIRO_EXTRA_INDEX, and on Windows ZIRO_NO_MODIFY_PATH.

Ziro is a normal Python package, so any installer that makes isolated environments works. Point it at the release index:

pipx install --index-url https://test.pypi.org/simple/ \
  --pip-args="--extra-index-url https://pypi.org/simple/" ziro

The two indexes are needed because Ziro publishes to TestPyPI today while its third-party dependencies resolve from prod PyPI. This is the same pair ziro upgrade uses.

What the install script does

Finds a suitable Python

Checks the py launcher and the usual interpreter names for one at 3.11.9 or newer, and stops with a clear message rather than failing deep inside pip. Set ZIRO_PYTHON to force a specific interpreter.

Creates an isolated environment

A plain venv at ~/.ziro/versions/<version>, built in a staging directory and renamed into place once the version is known. Nothing is installed into your system or user site-packages, and an existing install is never written to: the new version is built beside it.

Points the launcher at it

A one-line ~/.ziro/current file names the live version. The shims read it on every launch, so switching versions is a single atomic file replace.

Installs from the release index

Ziro from TestPyPI, dependencies from prod PyPI.

Puts a command on your PATH

Small wrapper scripts for ziro, ziro-once, and manage-agents in ~/.local/bin (macOS and Linux) or %LOCALAPPDATA%\Programs\ziro\bin (Windows). Only those three are exposed; the environment’s own python and pip stay off your PATH. On Windows the directory is added to your user PATH and to the current session. On macOS and Linux the script prints the line to add if the directory is not already there.

Verifies

Confirms the package reports a version and that the ziro command exists before claiming success.

Re-running the script installs the newest release beside the one you have and switches to it. ziro upgrade does the same thing from inside the app.

uv sync installs the runtime plus the local guardrail backends, Presidio for PII detection and Llama Guard for content safety, so guardrails work without any cloud service.

Optional dependency groups

Local voice
Dev extras

Push-to-talk speech in and out, running entirely on your machine: faster-whisper for speech-to-text and Piper for text-to-speech. No cloud key required.

uv sync --group voice-local

Voice is off by default and must also be enabled in the agent’s voice section of settings.yaml. Launch with python -m app.main --user <USER_ID> --voice, or toggle it in-session with /voice. See Voice.

Some tooling is only needed for development. The ASCII graph renderer, for instance, wants grandalf:

uv sync --group dev
python -m app.cli.show_graph

show_graph also emits Mermaid and PNG via --format mermaid or --format png (PNG needs the graphviz system package).

Pre-cache the local models

python -m app.cli.startup

This downloads only what is missing:

Asset	Used by	Why it matters
`all-MiniLM-L6-v2` embeddings	RAG, skills search, tool discovery	Roughly 20 seconds cold on first use, mostly network checks
spaCy model	The Presidio PII guardrail backend	Presidio cannot run without it
Llama Guard 3 1B GGUF	The Llama Guard content-safety backend	Large file; you do not want it downloading mid-conversation
Default Piper voice	Local text-to-speech	Only fetched when the `voice-local` group is installed

Run this before your first launch. Once the embeddings model is cached on disk, Ziro sets Hugging Face to offline mode at import, which removes roughly nine seconds of Hub metadata checks from every startup. A machine with nothing cached stays online and downloads once.

Embedding warmup is deliberately kept off the startup critical path: the UI appears before the model is ready, and any consumer that needs it waits for the real model rather than falling back to a degraded result.

Storage modes

The storage backend is selected by one environment variable. Set DATABASE_URL and Ziro runs in production mode; leave it unset and it runs entirely on local files.

Mode	Trigger	Long-term memory	Checkpoints	Vectors
Dev	no `DATABASE_URL`	`SqliteStore` (`./data/memories.db`)	`AsyncSqliteSaver` (`./data/checkpoints.db`)	FAISS
Prod	`DATABASE_URL` set	`PostgresStore`	`AsyncPostgresSaver`	pgvector

Dev mode

Nothing to do. Dev mode needs no infrastructure. SQLite files and a FAISS index under ./data/ are created on demand.

Production mode

Start PostgreSQL with the pgvector extension:

docker compose up -d

Then point Ziro at it by setting DATABASE_URL, either in ~/.ziro/.env directly, or through the wizard’s Advanced section (ziro setup) or the in-session /settings command. On the next build, the store, the checkpointer, and the vector store all switch over. See Environment variables.

The two modes are not synchronized. Threads and memories written in dev mode live in SQLite and are not visible after switching to PostgreSQL, and vice versa.

Where state lives

Ziro keeps configuration and per-user state outside the repository, so an installed package behaves the same as a source checkout.

Path	Contents
`~/.ziro/versions/<version>/`	One environment per installed release
`~/.ziro/current` and `previous`	The live version, and the rollback target
`~/.ziro/tools/`	The uv used to build environments (created on first upgrade)
`~/.ziro/.env`	API key, default model, Langfuse keys, `DATABASE_URL`
`~/.ziro/users.json`	The users registry, most-recently-used order, and the last user and flavour
`<DATA_DIR>/threads.json`	Per-workspace thread metadata: user, agent, flavour, title, timestamps
`~/.ziro/projects/<key>/`	Per-project memory, keyed by a stable workspace key
`~/.ziro/agents/<id>/`	Your overrides for a bundled agent, or an agent you added yourself
`~/.ziro/custom_providers.json`	Custom LLM provider labels (any OpenAI- or Anthropic-compatible endpoint)
`~/.ziro/plugins/`	Installed plugins at user scope
`./data/`	SQLite databases, the FAISS index, the model catalog cache, UI preferences

Checkpoints remain the source of truth for conversation content; threads.json only carries metadata. The workspace key is <basename>-<sha256 of the real path, first 8 chars>, so two same-named repositories in different directories never collide.

Config layering

Each agent is configured by one settings.yaml (with an optional section per concern), resolving most-specific-first across three roots and deep-merging per section:

<project>/.ziro/agents/<id>/  →  ~/.ziro/agents/<id>/  →  the bundled package

That means you configure an installed Ziro by dropping a settings.yaml under ~/.ziro/agents/<id>/ without ever editing the package. A section missing at every layer degrades to built-in defaults. Legacy split *_policy.yaml files still resolve as an alternative to the matching section. See Configuration.

Sections that can execute or widen access (permissions, mcp, hooks, plugins, and any matching split file) are skipped when they come from an untrusted project .ziro directory. Folder trust is content-hashed, so editing one of these revokes trust until you confirm it again.

Re-run the wizard

ziro setup

This re-opens the first-run wizard with every field prefilled, even when a key is already configured. Use it to re-key, switch the default model or provider, change theme, or add a custom provider. The same sections are reachable in-session with /settings.

Upgrade

ziro upgrade                  # install the latest release and switch to it
ziro upgrade --version 0.2.9  # install a specific one
ziro upgrade --list           # what is installed, and which one is live
ziro upgrade --rollback       # go back to the previous version

The new version is built in its own environment under ~/.ziro/versions/ and the current pointer is replaced only after it verifies. Nothing that is running is ever written to, which is what makes this safe on Windows: the old approach asked pip to replace the ziro.exe it was running from, and Windows locks a running image against writes. A failed download or a broken release leaves your working install exactly as it was. The two most recent versions are kept, so --rollback needs no download. The index host is configurable with ZIRO_PYPI_HOST and defaults to test.pypi.org.

Upgrades use uv when it is available, and fetch it into ~/.ziro/tools when it is not. An environment is roughly 1.2 GB across 55k files; uv hard-links them out of its cache, so a second version costs only the packages that actually changed. Without uv it falls back to pip, which copies every file and takes minutes rather than seconds.

Installs made by pipx, uv tool, or a source checkout are left to whatever made them: ziro upgrade runs the plain in-place pip upgrade there.

Optional extras

Extra	Command	What it gives you
SearXNG	`docker compose up -d searxng`	A self-hosted backend for `web_search`. Set `provider: searxng` and `searxng_url` in the agent’s `websearch` section. The default backend is keyless DuckDuckGo, so this is only needed if you want your own instance
PDF sandbox image	`docker compose build pdf-sandbox`	Builds `ziro-pdf:latest`, the container an agent with `mode: sandbox` in its `shell` section runs `run_shell` inside
PostgreSQL + pgvector	`docker compose up -d`	Production storage backend

There is no automatic fallback between web-search backends. If you configure searxng and the container is not running, the tool returns a readable error rather than silently switching to DuckDuckGo.

Index your own content

Two indexers extend what the agent can retrieve:

python -m ziro.rag.indexer ./my-docs/   # index a directory, a .txt, or a .pdf
python -m skills.loader                 # index every SKILL.md under ./skills/
python -m ziro.tools.indexer            # re-index tool descriptions

Use python -m ziro.<module> for the indexers. The app.* import alias redirects normal imports to their ziro.* equivalents, but python -m needs the real module path.

Verify the install

python -m app.cli.manage_agents list

This lists every agent with its on/off state and does not need a model call. It is a quick confirmation that the package, the agent folders, and the config layers all resolve.

Next steps

Quickstart

Run the wizard and hold your first conversation.

Environment variables

Every variable Ziro reads and what it changes.

Providers

OpenRouter, Anthropic, OpenAI, and custom endpoints.

Getting started

Concepts

Interfaces

Guides

Installation

Prerequisites

Choose an install path

What the install script does

Optional dependency groups

Pre-cache the local models

Storage modes

Dev mode

Production mode

Where state lives

Config layering

Re-run the wizard

Upgrade

Optional extras

Index your own content

Verify the install

Next steps

Quickstart

Environment variables

Providers

​Prerequisites

​Choose an install path

​What the install script does

​Optional dependency groups

​Pre-cache the local models

​Storage modes

​Dev mode

​Production mode

​Where state lives

​Config layering

​Re-run the wizard

​Upgrade

​Optional extras

​Index your own content

​Verify the install

​Next steps

Quickstart

Environment variables

Providers

Prerequisites

Choose an install path

What the install script does

Optional dependency groups

Pre-cache the local models

Storage modes

Dev mode

Production mode

Where state lives

Config layering

Re-run the wizard

Upgrade

Optional extras

Index your own content

Verify the install

Next steps