Configuration reference

Most settings can be supplied as a command-line flag or an environment variable; a few are environment-variable only (shown with - in the Flag column below). When a setting supports both and both are present, the environment variable wins - handy for baking defaults into a service definition while still overriding per run.

Options

Examples

Run on a custom port with a dedicated data directory:

hezo --port 8080 --data-dir /var/lib/hezo

Unlock a single startup non-interactively by passing the master key to that one invocation (Hezo normally starts locked and you unlock from the browser gate):

HEZO_MASTER_KEY="your twelve word master key phrase here" \
HEZO_DATA_DIR=/var/lib/hezo \
HEZO_WEB_URL=https://hezo.example.com \
  hezo

Pass HEZO_MASTER_KEY inline like this only for a one-off launch - never persist it to an env file, a service definition, or anywhere on the host. The master key is kept in memory only so a copy of your disk can't decrypt your data; writing it to disk defeats that. See Master key & encryption.

Using an external Postgres

By default Hezo embeds its database inside the single binary and stores it under the data directory - no external database to run. If you'd rather use a managed/hosted Postgres (for managed backups, more headroom, or your own operational tooling), point Hezo at it (this section is the reference; for a walkthrough on a cloud server see Managed database & asset storage or, for the cloud-init deploy, Using managed data hosting):

HEZO_DATABASE_URL="postgres://hezo:••••@db.internal:5432/hezo?sslmode=verify-full" \
  hezo --data-dir /var/lib/hezo

On first start Hezo checks the server version, then creates its schema by applying its migrations directly (each migration runs in its own transaction, guarded by an advisory lock so two instances can't migrate at once). Upgrades migrate the same way. The current backend and connection target (with credentials occluded) are shown under Settings → General → Database.

Requirements and recommendations:

• PostgreSQL 14 or newer. The version is checked at startup.
• Use TLS. With an external database your tasks, comments, and documents travel the network and live with the provider. Set sslmode deliberately - see TLS and sslmode for what each mode does and does not protect against. Secrets remain encrypted with the master key either way.
• Keep the database close to the server. Hezo's background scheduling polls every 1-5 seconds, so every millisecond of round-trip latency counts. Same-host, same-VPC, or same-region placement is strongly recommended.
• Direct connections or session pooling only. Transaction-pooling proxies (PgBouncer in transaction mode) break session-scoped advisory locks.
• One Hezo server per database. Concurrent startups coordinate migrations safely, but running two live servers against one database is not supported.
• The connection string carries credentials: prefer the environment variable over the flag (flags are visible in the process list), and never commit it to a repo.
• hezo backup / hezo restore work against an external database too - including moving an existing embedded instance to hosted Postgres (and back). See Backup & recovery.

TLS and sslmode

Hezo reads sslmode from the connection string exactly as psql and libpq do, so a connection string copied from your provider's dashboard behaves the same way in Hezo as it does in any other Postgres client:

Hezo logs the mode it resolved on every start, so you can confirm what you actually got:

Using external Postgres at postgres://••••:••••@db.internal:5432/hezo?sslmode=require
  (server 16.4, pool max 10, TLS encrypted, certificate not verified ...)

Verifying against a provider-private CA. Managed Postgres (DigitalOcean, AWS RDS, Azure) and most self-hosted servers present a certificate signed by their own CA rather than a public one, so verify-full on its own fails with "self signed certificate in certificate chain". Download the provider's CA certificate and point sslrootcert at it - this is the recommended setup:

# DigitalOcean: Databases → your cluster → Connection details → Download CA certificate
sudo install -m 644 ca-certificate.crt /etc/hezo/db-ca.crt

HEZO_DATABASE_URL="postgres://hezo:••••@db-postgresql-lon1-12345-do-user-0.db.ondigitalocean.com:25060/hezo?sslmode=verify-full&sslrootcert=/etc/hezo/db-ca.crt" \
  hezo --data-dir /var/lib/hezo

The PGSSLMODE environment variable is honoured only when the connection string carries no sslmode of its own, and node-postgres reads it strictly (every verifying mode means full verification). Put sslmode in the URL rather than relying on it.

Storing assets in S3-compatible object storage

By default, uploaded asset files (task attachments and the project assets library) live on the local filesystem under <data-dir>/assets/. To keep them in a bucket instead - for managed durability, or to keep the host closer to stateless - point Hezo at any S3-compatible store (deployment walkthroughs: Managed database & asset storage and Using managed data hosting):

HEZO_ASSET_STORAGE_URL="s3://ACCESS_KEY:SECRET@s3.eu-west-1.amazonaws.com/my-bucket/hezo-assets?region=eu-west-1" \
  hezo --data-dir /var/lib/hezo

One URL carries the whole configuration:

s3://ACCESS_KEY:SECRET@endpoint[:port]/bucket[/prefix]?region=…&pathStyle=…&tls=…

• endpoint - the storage host. AWS S3, MinIO, Cloudflare R2, DigitalOcean Spaces, Backblaze B2, and anything else that speaks the S3 API all work; only the S3 protocol is supported (no provider-native APIs).
• bucket[/prefix] - the bucket, plus an optional key prefix if the bucket is shared with other data. Objects are stored as [prefix/]<project-id>/<asset-id>.
• region - defaults to us-east-1 (many S3-compatible stores accept any value).
• pathStyle - defaults to true for custom endpoints (MinIO and friends) and false (virtual-hosted addressing) for *.amazonaws.com.
• tls - defaults to true; set tls=false only for local/dev endpoints.
• Percent-encode any /, +, or @ characters inside the access key or secret.

At startup Hezo verifies it can reach the bucket with the given credentials and exits with guidance if it can't. The active backend (with credentials occluded) is shown under Settings → General → Asset storage.

Recommendations:

• Use TLS and a private bucket. Asset bytes are served through the Hezo server with signed URLs - the bucket never needs to be publicly readable. Assets are stored as plain objects, so enable your provider's server-side encryption if you want them encrypted at rest.
• One Hezo server per bucket/prefix. Two live servers sharing a prefix is not supported (same posture as the database).
• The URL carries credentials: prefer the environment variable over the flag (flags are visible in the process list), and never commit it to a repo.

Switching an existing instance

hezo backup / hezo restore move an instance's assets between local storage and a bucket for you - they carry the database in the same backup bundle, so one pair of commands moves the whole instance (see Backup & recovery). To move existing assets into a bucket:

1. Stop the server.
2. Back up the instance: hezo backup --output move/. If your data directory isn't the default, point the command at it - hezo backup reads HEZO_DATA_DIR (so a deployment that already sets it needs nothing extra), or pass --data-dir. This writes the database and every asset file into move/.
3. Restore into the bucket: hezo restore move/ --asset-storage-url "s3://…" - add --database-url as well if you're also moving to hosted Postgres. Restored blobs are checksum-verified against the database rows.
4. Start the server with HEZO_ASSET_STORAGE_URL set.

Moving back to local storage is the same, restoring without --asset-storage-url. The backup only reads the source, so your original assets stay in place until you remove them yourself.

Because the local <data-dir>/assets/ layout and the bucket keys are identical (<project-id>/<asset-id>), you can alternatively sync the tree directly with any S3 tool while the server is stopped - aws s3 sync /var/lib/hezo/assets/ s3://my-bucket/hezo-assets/ (or rclone sync).

Anonymous usage telemetry

To help us understand how Hezo is used across self-hosted installs, each instance sends a small anonymous usage report once a day. It is on by default and easy to turn off.

What's sent - aggregate counts only:

• a random per-install id (a UUID generated on first report - it lets reports from the same install be counted once across days; it is not derived from you, your machine, or your data),
• the Hezo version, operating system, and CPU architecture,
• totals: number of teams, projects, and agents,
• task counts by status, and how many tasks were completed in the last 24 hours,
• agent-run count and total input/output tokens over the last 24 hours,
• the mix of AI providers used (e.g. how many runs used Anthropic vs. OpenAI).

What's never sent - project, team, or task names; prompts or any task content; repository details; user identities; secrets; or any monetary/cost figure. Aggregated numbers from all opted-in installs are shown publicly at hezo.ai/stats.

Turn it off with the flag or the environment variable:

hezo --disable-telemetry
# or
HEZO_TELEMETRY_ENABLED=0 hezo

You can also keep the data in-house by pointing --telemetry-endpoint (or HEZO_TELEMETRY_ENDPOINT) at your own collector.

See also

• CLI reference - commands and usage.
• Backup & recovery - --reset and restoring.
• First-run setup - the master key.