Getting Started

Your first working instance, from zero to a licensed server with an agent responding to messages.

What you'll need

A machine with 2+ CPU cores and 2 GB RAM (Linux, macOS, or Windows WSL2)
A carrier licence for the machine that will run hoziron-server (see below — this is not optional, and there is no bypass)
One of: a provider API key (Anthropic, OpenAI) or a local Ollama/vLLM instance
Docker, if you're not installing the binary directly

The carrier licence gate

Hoziron will not do meaningful work without a valid, signed carrier licence installed on the machine running hoziron-server. This applies to every install method and every routing mode — even a fully local/Ollama-only deployment needs a licence, because the routing gateway that dispatches every LLM call refuses to initialize without one. There is no environment variable, test flag, or config setting that skips this check.

Send your carrier ID and name to Hoziron. Licences are signed with a private key only Hoziron holds — carriers cannot self-issue a licence. Licence trust is bound to the carrier's contract, not to the machine running hoziron-server — there's no per-instance identifier to hand over first. Hoziron issues the licence and sends you the resulting licence.json file.
Install the licence file at $HOZIRON_HOME/licence.json on the machine running hoziron-server (/data/licence.json inside the Docker image, since HOZIRON_HOME=/data there). The server reads it at boot.
Start the server. If the licence is missing, the process refuses to boot with: No carrier licence found at <path>. A valid licence file is required to start the platform. If it's present but expired or has a bad signature, boot fails with a specific diagnostic instead. Cloud routing additionally stops (falling back to local-only) if the licence has expired — see ADR-034 for the full expiry-behaviour table.
Check it anytime with hoziron-cli licence status (add --json for scripting) — carrier name, expiry, workflow budgets used, cloud spend, once the server is up and the CLI is pointed at it.

This step comes before "start the server" in every install method below — the server binary starts, but immediately refuses to serve traffic without a licence in place.

Choose your install method

Method	Best for	Time to first agent
Binary install	Local dev, bare metal servers	~10 minutes (incl. licensing)
Docker	Container environments, quick eval	~10 minutes (incl. licensing)
Demo image	Seeing a live FNOL pipeline immediately, no licence request	~5 minutes (just an Anthropic key)

What happens during setup

Install — get the hoziron-cli (CLI) and hoziron-server binaries or the container image
Licence — get a signed licence bound to your carrier ID, install it at $HOZIRON_HOME/licence.json
Start — launch hoziron-server (serves the API surface by default; --surfaces selects others)
Configure a provider — declare a [[provider]] in config.toml (cloud or local/Ollama)
Connect the CLI — hoziron-cli context add + hoziron-cli onboard point the CLI at the running server
Install/activate an agent — via hoziron-cli catalog install <package> --activate, and start chatting

Quick reference

Command	What it does
`hoziron-cli licence status [--json]`	Show carrier, expiry, and budget usage of the installed licence
`hoziron-cli init [--quick]`	Initialize the CLI's local config directory (contexts only)
`hoziron-cli onboard [--quick]`	Interactive wizard: connect the CLI to a running server
`hoziron-cli context add/use/list`	Manage which server the CLI talks to
`hoziron-cli status [--json]`	Show platform status (agents, providers) — requires the `AgentList` role
`hoziron-cli health [--json]`	Quick, unauthenticated health check
`hoziron-cli doctor [--json] [--repair]`	Run local CLI-side diagnostics (with `--repair` to auto-fix)
`hoziron-cli agent chat <id>`	Interactive chat with an agent (no default — an ID is always required)
`hoziron-cli agent list` / `status <id>`	List/inspect agents
`hoziron-cli catalog search <query>` / `install <pkg> --activate`	Find and install an agent/skill/competency package

Environment variables

Variable	Purpose	Default
`HOZIRON_HOME`	Config/data directory for both the CLI and the server (checked before the fallback on every path resolution)	`~/.hoziron` (`/data` in the Docker image)
`HOZIRON_LOG`	Log filter directives for `hoziron-server` (e.g. `info`, `info,hoziron_core=debug`)	`info`
`HOZIRON_LOG_FORMAT`	Server log format (`text` or `json`)	`text`
`HOZIRON_URL` / `HOZIRON_API_KEY` / `HOZIRON_CONTEXT`	Read by `hoziron-cli onboard --quick` for non-interactive CLI setup	unset

Provider API keys (ANTHROPIC_API_KEY, etc.) aren't read from a .env file — see Install via Binary for how the server actually resolves them (process environment, or the daemon-owned vault via hoziron-cli config set-key).

Ready? Pick your install method and let's go.

Related: