Starting and Stopping the Server

The hoziron-cli CLI is an HTTP client — it never launches, embeds, or stops the server itself. The server is a separate binary, hoziron-server, run directly by the operator (foreground, systemd, or a container entrypoint).

Starting the server

Synopsis

hoziron-server [--config <path>] [--surfaces <list>] [--api-listen <addr>] \
    [--registry-listen <addr>] [--mcp-listen <addr>] [--dashboard-listen <addr>]

Flags

FlagDescription
--config <path>Path to config.toml (default: $HOZIRON_HOME/config.toml)
--surfaces <list>Comma-separated surfaces to enable (api,registry,mcp,dashboard), overriding each surface's enabled flag in config
--api-listen <addr>Override the API surface's listen address
--registry-listen <addr>Override the registry surface's listen address
--mcp-listen <addr>Override the MCP surface's listen address
--dashboard-listen <addr>Override the dashboard surface's listen address

Listen Address Resolution

Per surface, priority order (first match wins):

  1. The surface's --*-listen CLI flag (e.g. --api-listen)
  2. [surfaces.<surface>].listen in config.toml
  3. Built-in default (127.0.0.1:4200 for the API surface; see config.toml reference for the others)

There is no HOZIRON_LISTEN environment variable — set the address via the CLI flag or config file.

Examples

# Start with defaults from config.toml (foreground)
$ hoziron-server
INFO Starting Hoziron server surfaces=["api"]

# Start on all interfaces (containers, remote access)
$ hoziron-server --api-listen 0.0.0.0:4200

# Enable multiple surfaces explicitly
$ hoziron-server --surfaces api,registry

# Start with custom config
$ hoziron-server --config /opt/hoziron/config.toml

# Start with verbose logging
$ HOZIRON_LOG=debug hoziron-server

# Start in the background (dev only — prefer systemd/Docker in production)
$ hoziron-server &

What Happens on Start

  1. Loads configuration from $HOZIRON_HOME/config.toml (or --config)
  2. Boots the shared HozironPlatform (execution kernel + data directory)
  3. Registers configured providers (validates API key env vars exist)
  4. Refuses to boot any surface whose auth is effectively disabled on a non-loopback bind (see Authentication setup)
  5. Binds each enabled surface to its resolved listen address

Connecting the CLI to a running server

hoziron-server does not write a connection-discovery file — point the CLI at it explicitly with a context:

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

See context.md for remote/multi-instance setups.

Stopping the server

There is no hoziron-cli stop command. Stop the hoziron-server process the same way you'd stop any long-running service:

# Foreground: Ctrl+C (SIGINT)

# Background/systemd
sudo systemctl stop hoziron

# By PID
kill <pid>

# Docker
docker stop <container>

Graceful Shutdown Sequence

hoziron-server handles both SIGINT (Ctrl+C) and SIGTERM:

  1. Stops accepting new HTTP requests
  2. Suspends running agents (preserves state)
  3. Flushes memory stores to SQLite
  4. Closes database connections
  5. Exits with code 0

Notes

  • Give the process at least 30 seconds between SIGTERM and a hard kill to allow the flush to complete — systemd's default 90s stop timeout is more than sufficient

See Also