Self-Hosting

If you want to self-host GuideMode, contact us at info@guidemode.dev.

Self-hosting is offered to customers who need session transcripts and analytics to stay inside their own network. We provide the server image, the deployment files and a licence key. These pages describe what you are agreeing to run before you talk to us.

What you run

GuideMode self-hosted is one server image. The same image serves the API, the web UI, the background workers and the scheduled jobs, and it is also what runs database migrations. There is no second service to operate.

You run more than one of it. Every deployment shape here puts several instances behind a load balancer, including the single-host Docker one, because the alternative is a stack whose multi-instance behaviour is never exercised until the day it matters. Instances are interchangeable and hold nothing: no sticky sessions, no leader, and no instance that is special.

Around it you need two things:

Dependency	Requirement
PostgreSQL	Version 17. Any managed Postgres will do, and running one you already operate is a first-class choice rather than a fallback. No custom build: the only extension is pg_trgm, which is part of every standard distribution, and the migrations create it
S3-compatible object store	A bucket for session transcripts. MinIO, AWS S3 and Cloudflare R2’s S3 endpoint are all supported

Everything else GuideMode needs at scale - the queue, the job scheduler, rate limits, operation locks and the websocket fan-out that drives live progress - runs in Postgres. There is no Redis, no message broker and no separate scheduler to deploy.

Why the object store is not optional

Session transcripts are the one thing GuideMode stores outside Postgres. A local disk works on a single instance and half-works on two, because an upload lands on whichever instance served the request and returns a 404 from the other. Rather than ship a store that fails quietly at your second replica, a deployment either has an S3 bucket or has no transcript storage at all.

AI analysis runs on your keys

The AI features ship in every deployment, and they run on model credentials you supply. Set a key for your provider and session analysis, summaries and quality assessment are on; set none and they are off, and the rest of GuideMode works exactly as it does with them. Nothing is sent to us. See AI analysis.

Choosing a deployment

Shape	Best for	Guide
Docker Compose	One host. Evaluations, small teams, an internal instance. Runs three server instances behind a load balancer on that host	Docker
Kubernetes	Replicas across machines, rolling deploys with no dropped requests, an existing platform team	Kubernetes
Cloudflare Workers	Running GuideMode the way we run it, on your own Cloudflare account	Cloudflare

The same code runs in all three. The server detects what it has been given and adapts, so nothing in the application is aware of which one it is on. Every setting is listed in the configuration reference.

Three rules that apply everywhere

Migrations are a command, never a startup step. Run the migrate command as a one-shot job, then start the server. Several instances racing the migrator is a bad outcome, and a lock around it only makes the rest sit blocked while traffic arrives.

A server whose database is behind refuses to start. It names the command to run rather than serving errors from whichever page first touches a missing column. A database that is ahead is fine, since that is what a rolling deploy and a rollback both look like.

Configuration is validated at boot, all of it at once. A missing or half-configured setting stops the server with every problem listed, not just the first. An integration whose settings are absent is simply switched off, which is the normal state of most deployments.

What you need before you start

• A hostname with TLS in front of it. GuideMode builds every link in every email from it
• A Postgres 17 database and its connection string
• An S3 bucket, its endpoint and a key pair
• A 32-byte secret for encrypting stored OAuth tokens
• Optionally, credentials for the integrations you want: GitHub, Jira, Linear, Notion, Slack, and a sign-in provider

Versions, and how long they keep working

Self-hosting means your server and your engineers’ CLIs stop upgrading together. The promise that makes that safe:

A CLI works against servers up to six months older than itself, and a server accepts uploads from CLIs up to six months older than itself.

Each half is a number in the code rather than an intention. Every server states its own version and the oldest client it will make promises to at GET /api/version, and on two headers of every response it sends. The CLI reads them from a response it was already receiving, so the check costs no extra request, and tells the user in plain words when the pair has drifted:

guidemode.example.com runs GuideMode 0.1.51 and needs a CLI of at least 0.2.0;
this is 0.1.9. Run: npm install -g guidemode@latest

The check is per server, not per machine, because one CLI routinely talks to your instance and to the hosted one in the same week.

Set RELEASE_VERSION on your deployment, or build the image with --build-arg RELEASE_VERSION=<version>. A server that does not know its own version reports dev, and a client reads that as unknown and stays quiet — which is right for a laptop and useless for a production instance.

Support

Self-hosted deployments are supported directly. Every instance can produce a configuration report at GET /api/config-report, readable by a global administrator. It states what is configured and what is not, never a value, so the whole response can be pasted into a support conversation.

info@guidemode.dev