Install via Binary

What you'll accomplish: Download the hoziron-cli (CLI) and hoziron-server binaries, get a carrier licence installed, configure a provider, start the server, connect the CLI, and verify it's healthy.

1. Download and install

Binaries are published to dl.hoziron.com for every release. To install the latest release (Linux x86_64 example — see targets below for others):

TARGET="x86_64-unknown-linux-gnu"

curl -sSL "https://dl.hoziron.com/latest/hoziron-${TARGET}.tar.gz" -o hoziron-cli.tar.gz
tar -xzf hoziron-cli.tar.gz
sudo mv hoziron-*/hoziron-cli /usr/local/bin/
rm -rf hoziron-cli.tar.gz hoziron-*/

For the server binary (runs the unified API, registry, MCP, and dashboard surfaces):

curl -sSL "https://dl.hoziron.com/latest/hoziron-server-${TARGET}.tar.gz" -o hoziron-server.tar.gz
tar -xzf hoziron-server.tar.gz
sudo mv hoziron-server-*/hoziron-server /usr/local/bin/
rm -rf hoziron-server.tar.gz hoziron-server-*/

Available targets (from the release build matrix):

• x86_64-unknown-linux-gnu — Linux x86_64
• aarch64-unknown-linux-gnu — Linux ARM64
• aarch64-apple-darwin — macOS Apple Silicon (.zip instead of .tar.gz — use unzip in place of tar -xzf)

The hoziron-*/ glob works regardless of which release you downloaded, since the archive's internal directory name always embeds its own version. The extracted binary is named hoziron-cli.

Pinning to a specific version

Replace latest with the version number in the URL, and add the version into the filename:

VERSION="0.7.0"   # set to the release you want
TARGET="x86_64-unknown-linux-gnu"

curl -sSL "https://dl.hoziron.com/${VERSION}/hoziron-${VERSION}-${TARGET}.tar.gz" -o hoziron-cli.tar.gz
tar -xzf hoziron-cli.tar.gz
sudo mv hoziron-*/hoziron-cli /usr/local/bin/
rm -rf hoziron-cli.tar.gz hoziron-*/

There is currently no x86_64-apple-darwin (Intel Mac) release build.

Verify the install:

hoziron-cli --version
hoziron-server --version

2. Get a carrier licence

hoziron-server refuses to start meaningful work — including local-only, no-cloud-provider setups — without a signed carrier licence at $HOZIRON_HOME/licence.json. There is no bypass. Do this before starting the server:

Send your carrier ID and name to Hoziron to have a licence issued. Hoziron sends back a signed licence.json file.

Place that file at $HOZIRON_HOME/licence.json (default ~/.hoziron/licence.json) on this machine. Licence trust is bound to the carrier, not to this machine, so the file is portable across hosts running the same carrier's instance. See Getting Started: the carrier licence gate for the full flow and expiry behaviour. Once the server is running, hoziron-cli licence status shows the loaded licence's carrier, expiry, and budget usage — see step 6 below.

3. Initialize the CLI

hoziron-cli init

This creates ~/.hoziron/ with a minimal config.toml for the CLI's own state (contexts only — no server config, no provider keys). hoziron-cli init is CLI-side bookkeeping; it's independent of the server's $HOZIRON_HOME even when they happen to be the same directory on a single-machine dev setup.

For CI/scripts, use hoziron-cli init --quick to skip interactive prompts.

4. Configure a provider

The server reads its own config.toml (also under $HOZIRON_HOME by default, or --config <path>) for the [[provider]] inventory it's allowed to route to (ADR-053) — declare one or more providers explicitly:

# $HOZIRON_HOME/config.toml — cloud example
[[provider]]
id = "anthropic"
driver = "anthropic"
api_key_env = "ANTHROPIC_API_KEY"

  [[provider.model]]
  id = "claude-sonnet-4-20250514"

[routing_gateway.standard]
preference = [{ provider = "anthropic", model = "claude-sonnet-4-20250514" }]

Or for a local-only, air-gapped setup with Ollama:

[[provider]]
id = "ollama"
driver = "ollama"
url = "http://127.0.0.1:11434/v1"

  [[provider.model]]
  id = "llama3.1:70b"

[routing_gateway.local]
preference = [{ provider = "ollama", model = "llama3.1:70b" }]

routing_gateway.standard.preference (cloud-eligible) and routing_gateway.local.preference (local-only) are ranked lists — first entry wins. standard is the mandatory fallback whenever any provider is declared; local is mandatory whenever a Local-sovereignty provider is declared. See ADR-034 for the full routing model.

Provider API keys are not read from a .env file. api_key_env names an environment variable the server process reads at call time — export it before starting hoziron-server:

export ANTHROPIC_API_KEY=sk-ant-...

Or store it in the daemon-owned credential vault once the server is running (this works against a remote server too, unlike a local .env):

hoziron-cli config set-key anthropic
# Prompts for the key, PUTs it to the running daemon's /vault/ANTHROPIC_API_KEY

The vault is checked first, then the process environment — either is sufficient.

5. Start the server and connect the CLI

hoziron-server &

The API surface listens on 127.0.0.1:4200 by default (loopback-only; other surfaces — registry, mcp, dashboard — are disabled unless enabled via --surfaces or config.toml). If the licence from step 2 isn't in place, the process exits immediately with No carrier licence found at ....

Point the CLI at it:

hoziron-cli context add local --url http://127.0.0.1:4200
hoziron-cli context use local

Or run the interactive wizard, which does the same plus a connectivity check:

hoziron-cli onboard

6. Verify

curl http://127.0.0.1:4200/health

{
  "status": "healthy",
  "uptime_secs": 42,
  "latency_p95_ms": null,
  "version": "0.5.0",
  "agents": { "running": 0, "suspended": 0, "total": 0 },
  "providers": { "healthy": 1, "degraded": 0, "unavailable": 0 },
  "memory": { "state": "healthy" }
}

(latency_p95_ms is null until at least one request has completed since boot.) Or use the CLI:

hoziron-cli health
hoziron-cli licence status

If something's off, run hoziron-cli doctor for local diagnostics.

Next steps

You've got a running, licensed instance. Now create your first agent.

Related:

• Your first agent
• Install via Docker (alternative method)
• Troubleshooting startup issues