Self-Hosting

The Quickstart gets a single instance running in one command. This page is the production view: Docker Compose for a single box, the Helm chart for Kubernetes, the first-login flow, and the hardening you should do before exposing it to the internet.

Neither path needs a repo clone. Both pull published images and bring up the full stack: the API, the dashboard, Postgres, the Ory services (Kratos, Keto, Hydra, Oathkeeper), MinIO, flagd, and Valkey.

Or skip the ops entirely

Truss Cloud runs and manages all of this for you, plus multi-org, metering, and backups. Create an account if you would rather not operate it yourself.

Docker Compose

For a single host. Download the Compose file and an env template, fill in secrets, and start:

curl -fsSLO https://raw.githubusercontent.com/binarysquadd/truss/main/docker-compose.selfhosted.yml
curl -fsSL https://raw.githubusercontent.com/binarysquadd/truss/main/.env.selfhosted.example -o .env.selfhosted

# fill in every GENERATE_* value, e.g. with: openssl rand -hex 32

docker compose -f docker-compose.selfhosted.yml --env-file .env.selfhosted up -d

The dashboard is served at http://localhost:3000. (Prefer one command? The Quickstart installer does the download + secret generation for you.)

The MCP server is an optional add-on, off by default. Turn it on with docker compose -f docker-compose.selfhosted.yml --profile mcp up -d; it listens at http://localhost:8765/mcp.

By default the Compose file uses the published ghcr.io/binarysquadd/truss-* images. To build from source instead, clone the repo and uncomment the build: blocks in the file.

Kubernetes (Helm)

The chart is published as an OCI artifact, so one helm install pulls it directly. No operators, no clone:

helm install truss oci://ghcr.io/binarysquadd/charts/truss --version 0.1.0 \
  -n truss --create-namespace \
  --set secrets.encryptionKey=$(openssl rand -hex 32) \
  --set secrets.dbPassword=$(openssl rand -hex 16) \
  --set secrets.minioSecretKey=$(openssl rand -hex 16) \
  --set secrets.valkeyPassword=$(openssl rand -hex 16)

kubectl -n truss port-forward svc/truss-dashboard 3000:80   # → http://localhost:3000

Note

Use the latest chart version from the Releases page in place of 0.1.0. Pin a version in production rather than tracking the newest.

Images are pinned in the chart and overridable via images.*. For production set publicUrl + corsAllowedOrigins and front it with TLS. Toggle optional components with their flags (e.g. --set mcp.enabled=false).

First login

On first boot, with no account yet, Truss seeds a default admin so you can sign in immediately, the same way Grafana and Argo CD do. It only ever runs when the identity store is empty, so it never overwrites real users.

• Email: [email protected] (override with TRUSS_BOOTSTRAP_ADMIN_EMAIL).

• Password: set TRUSS_BOOTSTRAP_ADMIN_PASSWORD for a known value, or leave it blank and a random one is printed once to the API logs:

  docker compose -f docker-compose.selfhosted.yml logs truss-api | grep "Default admin"   # Compose
  kubectl -n truss logs deploy/truss-api | grep "Default admin"                            # Kubernetes

Change it right after logging in under Settings → Account → Change Password. To opt out entirely, set TRUSS_BOOTSTRAP_ADMIN=false and register the first user yourself.

See Configuration for the full list of environment variables.

Hardening (read before exposing to the internet)

• CORS_ALLOWED_ORIGINS — set to your dashboard origin(s). CORS fails closed; if unset, the browser app cannot reach the API (intentional).
• ENCRYPTION_KEY — a random 32+ char string used to encrypt saved connection passwords. If you lose it, those are unrecoverable. Set it once and back it up.
• COOKIE_SECURE — the session cookie is marked Secure only when you serve over HTTPS. Serving over plain HTTP keeps it off so the cookie is not dropped; set COOKIE_SECURE=true behind an HTTPS-terminating proxy the API cannot detect.
• TRUSS_ADMIN_IDENTITY_IDS — admin-only features (DB roles, migrations, backups, authz rules) are gated. Grant admin by setting this to your Kratos identity ID(s), comma-separated.
• Put the API behind TLS, run Postgres with backups (PITR), and never run with dev defaults.

Ready to stop running it yourself?

If self-hosting has done its job and you would rather hand off the ops, Truss Cloud is the same platform, hosted and managed, with multi-org, metering, and managed backups. Your client code and API surface stay the same.