From cc9c2c427c38358cd98cf38ee5bb0059d5fd5de0 Mon Sep 17 00:00:00 2001
From: Jan Ehrhardt <59441+jehrhardt@users.noreply.github.com>
Date: Sun, 5 Jul 2026 19:18:02 +0200
Subject: [PATCH] docs(agents): update AGENTS.md

---
 AGENTS.md | 46 +++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 39 insertions(+), 7 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 3745090..6345925 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,14 +1,46 @@
 # Guidelines for agents
 
-`nightd` is a daemon that runs on a server and polls Linear. It automatically picks tickets and applies the following steps:
+## What is nightd
 
-1. Create workspace for the ticket
-2. Launch OpenCode session for the ticket in the background
-3. Track the linked pull request for the change
-4. Launch additional sessions to react to review comments
-5. Clean everything up after merging or closing the pull request
+Nightd is a hosting service for Omnigent, an open source AI agent framework and meta-harness that orchestrates Claude Code, Codex, Cursor, Pi, and custom agents developed mainly by Databricks. Omnigent follows a control plane / data plane architecture with a server that acts as control plane and a runner that acts as the data plane. It also provides a UI (web, desktop app, mobile app) and a CLI. Omnigent itself is single-tenant.
 
-This project uses mise to manage the development environment and run common tasks. Do not add Makefiles.
+Nightd provides Omnigent hosting by acting as a multi-tenant proxy in front of the Omnigent server's API. Each tenant gets its own Omnigent server under a dedicated subdomain. Apps, CLI and runners can connect to the server through nightd's proxy.
+
+### Authentication
+
+Authentication is handled by nightd in a multi-tenant way, where a user can sign-in and then access a server. A user can have access to one or multiple servers.
+
+Nightd uses Omnigent's header authentication. It reads a token from cookie or bearer token, verifies the token and forwards the user's email via `X-Forward-Email` header to Omnigent.
+
+### Serverless Hosting
+
+Nightd targets indie hackers and small teams. Therefore, we assume many servers with low traffic and data per server. To make the hosting efficient a serverless approach must be implemented.
+
+#### Scale to Zero
+
+Nightd acts as a proxy in front of Omnigent servers and must start a server ad-hoc, when it is not running. It tracks the life cycle of each server and scales it to zero, when a server is idle.
+
+#### Database
+
+Each Omnigent server requires its own database. Nightd uses SQLite as a database for Omnigent to put each server's state in a single file.
+
+SQLite forces nightd to run not more than one instance per Omnigent server.
+
+## Architecture
+
+This is a mono-repo with multiple apps written in Go. It uses mise to setup the development environment and implement common tasks.
+
+### Apps
+
+There are three apps in this project that are build as separate binaries and shipped as separate container images.
+
+- gateway: handles authentication and forwards requests to the Omnigent server of the current tenant
+- api: control plane that manages the life cycle of Omnigent servers and provides the correct routing to the gateway
+- node: data plane that launches an Omnigent server inside a Linux container on a concrete node
+
+The api app is the only one that uses a Postgres database and provides an API. The gateway acts only as a proxy for Omnigent API. The node connects itself to the api to receive instructions.
+
+The API provided uses gRPC.
 
 ## Credentials
 
-- 
2.51.2