Getting started

This guide gets a tendant server running on a machine in your home and pairs your first device.

What you need

• A machine to run it: NixOS, or anything that runs Docker.
• PostgreSQL 15 or newer with the pgvector extension. tendant creates its tables itself on first start; pgvector has to be installed by an admin because tendant’s own database user isn’t allowed to.
• Optional, for agent help with triage: Ollama with gemma4:12b (reliable tool calls; about 8 GB) and nomic-embed-text (category matching). Any OpenAI-compatible endpoint, or a hosted model, works too.

Run it

Pick one of the deployment guides. Both set up the database, pgvector and backups for you:

• NixOS (recommended): Deploy on NixOS.
• Docker Compose: Deploy with Docker Compose.

Running the bare binary? It’s tendant serve, configured as described in Configuration. At a minimum set:

Setting	Why
DATABASE_URL	The Postgres database (with pgvector installed).
TENDANT_PASSWORD	The device-pairing password. Without it no device can pair (the log says “device pairing disabled”).
TENDANT_CREDENTIALS_KEY	openssl rand -base64 32. Encrypts the tokens of the sources you connect and the homefirst.cloud keys. Back it up separately from the database.

Check it’s up: curl -fsS http://localhost:8080/healthz.

Pair your first device

1. Open the web UI (http://<host>:8080, or your tailnet address) or the app.
2. Enter the pairing password (TENDANT_PASSWORD).
3. Pair your other devices (phone, desktop app) the same way, or sign in with SSO if you’ve configured OIDC.

A tendant server has a single owner: every paired device is a session of that owner and sees the same tasks and inbox. There are no separate per-person accounts yet.

Tip

Keep tendant on your tailnet rather than the public internet. The pairing password can be reused — anyone who reaches the server and knows it can pair, and gets the owner’s full access.

Give it a model (optional)

Out of the box tendant routes everything to you. To let agents triage and help, add a model connection and point the agent at it:

[[llm_connections]]
name = "local-ollama"
provider = "openai"            # Ollama speaks the OpenAI protocol
base_url = "http://127.0.0.1:11434"
model = "gemma4:12b"
reasoning_effort = "none"      # gemma4 thinks by default; "none" is ~6x faster

[agent]
connection = "local-ollama"

[overseer]
connection = "local-ollama"

On NixOS, the Laya decision model (services.homefirst.laya.enable = true) answers triage questions locally with one call instead of an LLM conversation.

Next: connect the sources tendant should watch.