Kiteyard Setup

For humans / Guided hand-off

Keep the decisions. Delegate the mechanics.

Point a capable coding agent at the stable setup runbook. It will inspect first, ask for one decision at a time, and use the canonical Kiteyard installer.

Use a fresh, dedicated server.
This guide is for a new single-customer installation, not an upgrade or migration.

Point your agent at this site to begin guided setup.

Copy one short instruction that sends it to the stable, machine-readable runbook.

Before you start

Know what the agent will need.

PostgreSQL is included. Optional integrations can wait until the core passes verification.

Required

Host and origin

  • A dedicated linux/amd64 server with root or passwordless sudo.
  • Docker Engine, Docker Compose 2.20+, Node.js 24, and Git.
  • An exact private HTTPS origin with DNS and a reverse proxy or private ingress.
Required

Accounts and access

  • A classic GitHub PAT with read:packages for the private application packages ghcr.io/kiteyard/headquarters and ghcr.io/kiteyard/agent-manager. The separate ghcr.io/kiteyard/agent-manager-worker-runtime image is public and does not use this PAT.
  • An initial administrator email and a unique password of at least 12 characters.
  • A ChatGPT plan with Codex access before real Agent Manager jobs run.
Recommended

Practical starting size

  • At least 4 vCPU, 8 GiB RAM, and 40 GiB SSD, then size for build concurrency.
  • A reviewed release tag or full commit and compatible image tags or digests.
  • Off-host backup destinations for the database, configuration, and worker volumes.

What happens next

A staged installation with stop conditions.

The agent should not jump ahead to optional features when the core is unhealthy.

Plan and preflight

Confirm scope, architecture, host suitability, versions, ports, DNS, and existing Docker state using read-only checks.

Authenticate sources

Pin a reviewed repository revision and use the package-read PAT only for pulls of the private ghcr.io/kiteyard/headquarters and ghcr.io/kiteyard/agent-manager packages. The public ghcr.io/kiteyard/agent-manager-worker-runtime image remains separate. Never record the PAT in Kiteyard’s environment file.

Prepare operator input

Set the HTTPS origin and administrator details in a protected host file. The installer generates internal secrets.

Install the core

Run deploy/core/install.mjs. It writes the retained installation to /opt/kiteyard and starts the canonical Compose stack.

Verify every boundary

Check service state, migrations, loopback access, the public route, browser sign-in, and the expected built-in defaults.

Add selected options

Configure OpenAI embeddings, ChatGPT device login, Portainer, or external MCP clients only when you choose them.

Record and back up

Capture non-secret versions and decisions, then protect the retained environment, database, worker data, and recovery path.

After the core is healthy

Connect the people and agents that will use it.

These are separate credentials with different authority. Keep them distinct.

Authenticate Agent Manager jobs

In Agent Manager, disable and drain the managed worker before changing its login. Open Global Settings → ChatGPT Authentication Profiles, start the device login for Default (legacy), finish it in your own browser, then re-enable the worker.

A ChatGPT/Codex login is not an OpenAI API key. The optional OPENAI_API_KEY enables Headquarters document embeddings and semantic search.

Create a workspace MCP identity

  1. Open Settings → Users → Add User.
  2. Choose Agent, give it a clear name, and grant only the workspaces it needs.
  3. Open Settings → MCP in the intended workspace.
  4. Select the Agent, leave Agent Manager tools off for routine planning access, create the token, and store it in a secret manager.

Agent Manager MCP grants are installation-wide operational authority. They are off by default and should remain off unless that authority is explicitly required.

Optional MCP clients

Connect Codex or Claude Code.

Replace the host, keep the token in the client’s secret environment, and verify with a read-only workspace query first.

Codex

Make KITEYARD_MCP_TOKEN available to the Codex process, then register the server:

codex mcp add kiteyard \
  --url https://YOUR-KITEYARD-HOST/mcp \
  --bearer-token-env-var KITEYARD_MCP_TOKEN
codex mcp list
codex mcp get kiteyard --json

Official Codex MCP reference ↗

Claude Code

Read the token without echoing it and create a user-scoped HTTP connection:

read -rsp 'Kiteyard MCP token: ' KITEYARD_MCP_TOKEN; echo
claude mcp add --transport http kiteyard --scope user \
  https://YOUR-KITEYARD-HOST/mcp \
  --header "Authorization: Bearer $KITEYARD_MCP_TOKEN"
unset KITEYARD_MCP_TOKEN
claude mcp list

Official Claude Code MCP reference ↗

Optional and separate

Portainer can manage environment infrastructure later.

Portainer is not a core prerequisite. It may run on the same physical server or a separate environment VPS, but keeps its own Compose lifecycle. Agent Manager needs both managed and strict read-only private HTTPS MCP endpoints plus their two distinct credentials. Configure all four values together only after the core passes verification.

Read the full Portainer stage →