gotoi — self-hosted auto-remediation

Alert → plan → agent → execution. Middleware decides, the agent executes, and the dashboard shows the loop. The AI desk lets an assistant work on your hosts through the same agent, under your command policy and approval.

Use cases: docs/use-cases/. Template catalog: docs/templates.md. Production install: deploy/README.md (operator) and docs/DEPLOY.md (architecture).

Status: preproduction — the deploy/ Compose stack is the supported install path for a single operator-owned instance on one host. One middleware replica, no HA, no Kubernetes/Helm-managed multi-tenant hosting.

Production

cd deploy
cp .env.example .env
# four secrets and a Postgres password: openssl rand -hex 32
docker compose up -d --build

Open the public URL /setup and create the first admin. Agents enrolled before 0.1.0 must re-enroll.

Tagged releases also publish gotoi-middleware, gotoi-dashboard, gotoi-docs, and gotoi-marketing container images, plus generic package gotoi-agent, to packages. Compose still builds from source.

Development

Defaults listen on 127.0.0.1. Override the host with GOTOI_DEV_HOST (scripts) and GOTOI_BIND_ADDR (infra compose).

python3 scripts/tui.py          # or: bash scripts/dev.sh
cd middleware && bun install && bun src/server.ts   # :3100
cd dashboard && bun install && bun run dev          # :5173
cd infra && docker compose up -d                    # Postgres and the lab stack

server.ts exits if DATABASE_URL or GOTOI_AUTH_SECRET is unset. Dev scripts default DATABASE_URL to postgres://gotoi:gotoi@${GOTOI_DEV_HOST:-127.0.0.1}:5433/gotoi.

How it works

Prometheus ──alert──▶ Alertmanager ──POST /webhooks/alertmanager──▶ middleware
                                                                      │
                                                    per-source mapping, then
                                                        match rules bind a plan
                                                                      │
                                                             Execution (enqueued)
                                                                      │
                                      Go agent polls GET /agent/:id/:token/job
                                                                      │
                                      Agent runs steps, POST .../result

Push (webhooks) and pull (Checkmk, Grafana, Uptime Kuma) are both live. Guided setup is /alerts/sources/new.

Configuration

Middleware	Role
DATABASE_URL	Postgres. Required.
GOTOI_AUTH_SECRET	Better Auth. Required.
GOTOI_PLAN_SECRET	Plan-stamp HMAC. Required in production. Dev fallback dev-plan-secret.
GOTOI_SECRETS_KEY	AES-256-GCM key for the operator/org secrets store. Required in production. Dev fallback dev-secrets-key.
GOTOI_WEBHOOK_SECRET	Optional legacy bearer for hash-less migrated sources. New sources use a per-source ingest token.
GOTOI_WEBHOOK_RATE_PER_MIN	Max webhook POSTs per source per minute (default 600).
GOTOI_SOURCE_EXEC_PER_MIN	Max matched executions per source per minute (default 60).
GOTOI_MAX_RUNNING_PER_ORG	Running executions per org, under GOTOI_MAX_RUNNING (default 10).
GOTOI_PULL_TIMEOUT_MS	Pull fetch timeout (default 10000).
GOTOI_PUBLIC_URL	Public origin (compose).
GOTOI_DASHBOARD_ORIGIN	Extra Better Auth trusted origins.
GOTOI_ENROLL_TOKEN	Optional shared enroll secret.
GOTOI_PLANS_DIR	Plan git checkouts.
GOTOI_AGENT_RELEASES_DIR	Directory of agent binaries served to agents.
GOTOI_MAX_RUNNING	Cap on running executions.
GOTOI_AI_API_KEY, GOTOI_AI_API_BASE, GOTOI_AI_MODEL, GOTOI_AI_MODELS	Optional model for plan authoring. OPENROUTER_API_KEY is accepted as the key.
GOTOI_COMPACTION_KEEP_RECENT_TOKENS, GOTOI_COMPACTION_RESERVE_TOKENS	Chat compaction budgets.
PORT, HOST, NODE_ENV	Listen address. NODE_ENV=production enforces the secrets above.
GOTOI_DEV_BYPASS_AUTH	Skip Better Auth in dev so the seed admin works without the dashboard proxy.
GOTOI_DEV_SEED_USER	Dev seed admin email when bypass auth is on.

Dashboard	Role
GOTOI_MIDDLEWARE_URL	Middleware base for the server proxy. Default http://127.0.0.1:3100.
GOTOI_ENROLL_TOKEN	Injected on enroll calls.
PUBLIC_GOTOI_MIDDLEWARE_URL	Server URL baked into agent install commands.
ORIGIN	Public origin of this console (SvelteKit).
PORT	Listen port. Production image uses 5173.

Agent	Role
GOTOI_SERVER	Middleware URL.
GOTOI_HOSTNAME	Host this agent claims jobs for.
GOTOI_AGENT_ID, GOTOI_AGENT_TOKEN, GOTOI_AGENT_SECRET	Enroll credentials. The secret signs claimed jobs.
GOTOI_ENROLL_TOKEN	Presented at enroll.
GOTOI_CONFIG_DIR, GOTOI_STATE_DIR	Config and outbox directories.
GOTOI_HEARTBEAT	Heartbeat interval.
GOTOI_AI_API_KEY, GOTOI_AI_API_BASE, GOTOI_AI_MODEL	Optional, for gotoi-agent pi only.
GOTOI_UPDATE_ALLOW_UNSUPERVISED	Allow an unsupervised binary update.

API

Routes are grouped by file under middleware/src/routes/. Caddy publishes /agent, /webhooks, /healthz, and /ops/kill. /metrics stays on the private network.

Prefix	File
/healthz /overview /services /events /metrics /alerts	meta.ts
/webhooks/:source	webhooks.ts
/sources	sources.ts
/plans /audit	plans.ts
/rules	rules.ts
/executions	executions.ts
/incidents	incidents.ts
/agent	agent-api.ts, agent-updates.ts
/agents	agents.ts, agent-updates.ts
/machines	machines.ts
/groups	groups.ts
/organizations	organizations.ts
/invites	invites.ts
/profiles	profiles.ts
/changes	changes.ts
/control	control.ts
/ops	ops.ts
/settings	settings.ts
/auth /me	auth.ts

Security

• A claimed job is HMAC-SHA256 over planId|version|commit|executionId|issuedAt with that agent's enroll secret. GOTOI_PLAN_SECRET signs plan stamps only.
• /webhooks requires Authorization: Bearer equal to the source ingest token. Unknown ids return 401 and are not auto-created. Hash-less migrated sources still accept GOTOI_WEBHOOK_SECRET.
• The console uses Better Auth cookies. The dashboard proxy injects the enroll token. Console fire-test uses POST /sources/:id/test with the session.
• Production boot requires DATABASE_URL, GOTOI_AUTH_SECRET, and GOTOI_PLAN_SECRET.
• Run one middleware replica. It keeps state in memory and flushes whole tables to Postgres.

Tests

cd middleware && bun test
cd dashboard && bun run check && bun run test && bun run build
cd agent && go test ./...
gofmt -l agent   # must be empty
python3 docs/use-cases/_check.py
python3 scripts/check-type-mirror.py
python3 scripts/check-ai-headers.py

Layout

gotoi/
├── deploy/         # Postgres, middleware, dashboard, docs, Caddy
├── middleware/     # Bun/Fastify. Dockerfile at middleware/Dockerfile
├── dashboard/      # SvelteKit. Dockerfile at dashboard/Dockerfile
├── docs-site/      # Operator docs site: Next.js + fumadocs, static export
├── agent/          # Go agent
├── docs/DEPLOY.md    # deployment architecture
├── infra/          # Lab compose: Postgres, Prometheus, Alertmanager, Grafana, Checkmk
├── scripts/        # tui.py, dev.sh, build-agent.sh
├── docs/use-cases/ # Behavioural catalog
├── docs/templates.md # Copy-and-edit plan library
└── .forgejo/       # CI, agent release, and container image publish

Deployment

See deploy/README.md for the operator runbook and docs/DEPLOY.md for the architecture reference. For Kubernetes, see docs/DEPLOY-K8S.md. For Postgres storage, see docs/DEPLOY-DATABASE.md.

Cutting a release

See RELEASING_INSTRUCTIONS.md. It is the only procedure for tagging, bumping versions, publishing binaries and container images, and rolling them back.

License

Apache-2.0. Copyright 2026 Eduardo Garcia Aparicio.