Configuration

Longhouse works with zero configuration for local use. These options matter when you bind beyond localhost or run on a shared machine.

Authentication

Auth is disabled by default for local-only quickstarts. To add password protection:

terminal

LONGHOUSE_PASSWORD=your-password longhouse-server serve

For production, use a pre-hashed password so the raw value never sits in the environment. hash-password prompts for the password on stderr and prints only the hash, so it is safe to capture:

terminal

export LONGHOUSE_PASSWORD_HASH="$(longhouse-server hash-password)"
longhouse-server serve --host 0.0.0.0 --domain longhouse.example.com

What it prints is pbkdf2_sha256$<iterations>$<salt>$<derived>. An argon2 or bcrypt hash you produced elsewhere also verifies, provided that library is installed in the server environment.

A public bind without auth is refused, not warned about. If you pass --host 0.0.0.0, --host ::, or --domain with no password configured, longhouse-server serve prints what to set and exits non-zero. Pass --allow-public-no-auth only when something in front of it — a reverse proxy that authenticates — already does the job.

Host and port

The Runtime Host binds to 127.0.0.1:8080 unless you say otherwise, and the flags are the only thing that changes the bind:

terminal

longhouse-server serve --port 9090
longhouse-server serve --host 0.0.0.0 --port 80

The environment does not move the bind. LONGHOUSE_HOST and LONGHOUSE_PORT feed the resolved configuration that longhouse-server config show and local-health report — they do not change where serve listens. Exporting LONGHOUSE_HOST=0.0.0.0 and starting the server leaves it on loopback. Use --host.

Data location

The SQLite database is stored at ~/.longhouse/longhouse.db by default. Override it with DATABASE_URL or with --db:

terminal

DATABASE_URL=sqlite:///path/to/your.db longhouse-server serve
longhouse-server serve --db sqlite:///path/to/your.db

Environment variables

Variable	Default	Description
`LONGHOUSE_PASSWORD`	(none)	Plaintext password for browser auth
`LONGHOUSE_PASSWORD_HASH`	(none)	Pre-hashed password. `hash-password` emits pbkdf2_sha256; argon2 and bcrypt hashes also verify
`DATABASE_URL`	`sqlite:///~/.longhouse/longhouse.db`	SQLite database URL
`AUTH_DISABLED`	(unset)	Turns auth off. `serve` sets it to `1` for you on a loopback bind, and never on a public one.
`LONGHOUSE_HOST` / `LONGHOUSE_PORT`	`127.0.0.1` / `8080`	Resolved config reported by diagnostics. Does not change the `serve` bind — use `--host` / `--port`.
`LONGHOUSE_PUBLIC_URL`	(none)	Public URL shown to clients when no `--domain` is stored
`LONGHOUSE_URL`	(none)	Runtime Host address the installer stores for `longhouse auth`
`LONGHOUSE_DEVICE_TOKEN`	(none)	Device token read by `longhouse auth`
`LONGHOUSE_IMPORT_SCOPE`	(asks)	Read by the installer: `now`, `all`, or a date such as `2026-09-01` answers what history to import without a prompt
`LONGHOUSE_ALLOW_INSECURE_HTTP`	(unset)	Set to `1` to let native clients use plain http to a LAN address. Tailscale and loopback never need it
`LONGHOUSE_COOKIE_SECURE`	(unset)	Set to `1` to force `Secure` auth cookies when a TLS proxy the server does not trust reports every request as https
`FORWARDED_ALLOW_IPS`	loopback	Proxy addresses trusted to report https through `X-Forwarded-Proto` (uvicorn setting)

Machine name

A machine is named by its device token. A token created on the Devices page carries the name you gave it, and longhouse auth stores that name; browser approval names the token after this machine's hostname, or after --device when you pass it:

terminal

longhouse auth --url https://you.longhouse.ai --device my-vps

With an existing token, --device must match the token's own name; longhouse auth refuses a different one rather than store a pair the Runtime Host would reject. To rename a machine, connect it with a token of the new name, then restart the Machine Agent with longhouse machine repair --repair-service.

Running on a server

For an always-on machine (VPS, Mac mini, homelab), the typical setup:

terminal

export LONGHOUSE_PASSWORD_HASH="$(longhouse-server hash-password)"
export JWT_SECRET=$(openssl rand -hex 32)
export INTERNAL_API_SECRET=$(openssl rand -hex 32)

longhouse-server serve --host 0.0.0.0 --domain longhouse.example.com

Put a reverse proxy (nginx, Caddy) in front for TLS — reverse_proxy 127.0.0.1:8080 is the whole Caddy config. The hosted plan handles all of this if you prefer not to run infrastructure.

Without TLS, native clients accept plain http:// to loopback and Tailscale addresses, and to a LAN address only after an opt-in (see Quick Start). Browser login also works over plain http: auth cookies are marked Secure only for requests that arrive over https. A TLS proxy on another machine or container must be listed in FORWARDED_ALLOW_IPS for its requests to count as https.