Skip to content

Deploy aidy-server

Hosts written in Python, Go or any other language run the aidy runtime as its own service with aidy-server serve, from the @aidy-dev/server package or the Docker image ghcr.io/aidy-dev/aidy-server. Your reverse proxy sends aidy’s paths to it, and aidy calls your API back as the user. JavaScript hosts can embed the runtime instead; see Hono and Express.

browser ──> reverse proxy (console.example.com)
├─ /aidy/v0/*, /mcp, /skill.md, /llms.txt, /.well-known/... ──> aidy-server ──> Postgres
└─ everything else ─────────────────────────────────────────> your API
aidy-server ──(Authorization + Aidy-Assertion)──> your API

aidy-server serve reads its whole configuration from environment variables; there is no config file. The required ones:

Variable Meaning
AIDY_URL Public URL of this aidy instance, the assertion iss. https://console.example.com when the proxy serves aidy at the root.
AIDY_HOST_ORIGIN Your product’s origin, the assertion aud.
AIDY_SIGNING_KEY aidy’s private Ed25519 JWK with a kid, as JSON (see Signing keys).
AIDY_SECRET 32 or more bytes, used to seal settings such as model API keys at rest.
AIDY_DATABASE_URL postgres://… for production, or sqlite:<path> for a single instance. aidy creates its own aidy_* tables; give it its own database or schema.

Optional:

Variable Meaning
AIDY_HOST_BASE_URL Where aidy reaches your API, when it differs from the origin (an in-cluster service). Assertions still name the public origin in htu.
AIDY_HOST_OPENAPI Path or URL of your OpenAPI 3.1 document, fetched with the user’s credential. Default /api/openapi.json.
AIDY_MODELS The default model chain as a JSON array of {id, provider, model, baseURL?, apiKey?, vision?, temperature?, maxOutputTokens?, cooldownSeconds?, providerOptions?}; provider is openai-compatible, openai or anthropic, and cooldownSeconds is {quota, rateLimit, error}. Admins can change it in the app.
AIDY_HOST_KEYS JSON array of public JWKs your host signs Aidy-Host-Assertions with: deferred-task completions and host jobs (POST /aidy/v0/generate).
AIDY_PREVIOUS_SECRET The secret before a rotation: it still unseals saved settings, which are sealed again with AIDY_SECRET on first read. Remove it afterwards. See The settings secret.
AIDY_NAME The assistant’s name, served at GET /aidy/v0/info for the UI. Default Aidy.
AIDY_INSTRUCTIONS System instructions, or @path to read them from a file.
AIDY_SKILL_GUIDE Hand-written guide placed first in /skill.md, or @path.
AIDY_SKILL_NAME The /skill.md frontmatter name, a slug. Default: the product’s slug (valid even for a non-ASCII product name), else the first label of the host’s hostname.
AIDY_CLI_COMMAND, AIDY_CLI_PACKAGE, AIDY_CLI_INSTALL The CLI that /skill.md and /llms.txt name, and how to install it: its npm package, or a free-form install line (which wins), e.g. curl -fsSL https://tm.example.com/install.sh | sh. Default aidy from @aidy-dev/cli.
AIDY_KNOWLEDGE_DIR, AIDY_KNOWLEDGE_BASE_URL A directory of Markdown documents indexed at start for search and answers, and the URL their pages live under. See Knowledge.
AIDY_MCP_AUTHORIZATION_SERVERS Comma-separated OAuth issuers advertised to MCP clients.
AIDY_BASE_PATH Prefix of every route when aidy is served below a path.
AIDY_MAX_STEPS Model steps per run. Default 16.
PORT Listening port. Default 8080.

A missing variable, or one that is not valid JSON or in range, stops the server with a message naming it and exit code 2.

Terminal window
AIDY_URL=https://console.example.com \
AIDY_HOST_ORIGIN=https://console.example.com \
AIDY_HOST_BASE_URL=http://console-api.default.svc:8000 \
AIDY_HOST_OPENAPI=/openapi.json \
AIDY_SIGNING_KEY="$(cat aidy-2026-11.private.jwk)" \
AIDY_SECRET="$(openssl rand -base64 48)" \
AIDY_DATABASE_URL=postgres://aidy:…@db/aidy \
AIDY_MODELS='[{"id":"qwen","provider":"openai-compatible","model":"qwen3-max","baseURL":"https://dashscope.aliyuncs.com/compatible-mode/v1","apiKey":"…"}]' \
npx @aidy-dev/server serve

npm install -g @aidy-dev/server installs the same binary as aidy-server. GET /healthz answers ok. On SIGTERM or SIGINT the server stops accepting requests and waits for runs in progress.

aidy creates and upgrades its tables (aidy_*) on start. Several replicas can share one Postgres; see Several instances.

When aidy is embedded, the same settings are createAidy options: name, instructions, secret (a string, or a list to rotate), and skill: { name?, guide?, cli?: { command, package?, install? } }.

aidy signs every call to your API with an Ed25519 key. Generate one with either command:

Terminal window
aidy keys generate --kid aidy-2026-11 -o aidy-2026-11.private.jwk # @aidy-dev/cli
npx @aidy-dev/server keys aidy-2026-11 # aidy-server

aidy keys generate prints the public JWK and writes the private JWK to a new 0600 file. Both commands write portable JWKs, {kty, crv, x, kid} and {kty, crv, x, d, kid} without alg, key_ops or ext, so Node, Bun, Deno and workerd import them alike. In code, load the private key with importSigningKey from @aidy-dev/spec/delegation: it also accepts a JWK that Node exported with alg: "Ed25519", which workerd refuses to import as is, and importPublicKeys does the same for public keys. aidy-server keys <kid> prints both as one JSON object, {"signingKey": …, "publicKey": …}: signingKey is the value of AIDY_SIGNING_KEY, so run it where its output is not logged. The private key is aidy’s secret: give it to the aidy service only. The public JWK goes into your host’s configuration (for example load_public_keys in the Python kit). aidy also serves it at /.well-known/aidy-keys.json for inspection; hosts pin keys in configuration and never fetch them from a request.

  1. Generate a new key with a new kid.
  2. Add the new public JWK to every host, next to the old one, and deploy.
  3. Switch aidy’s AIDY_SIGNING_KEY to the new private key and deploy.
  4. After a minute (assertions live 60 seconds), remove the old public key from the hosts.

Generate AIDY_SECRET once, for example with openssl rand -base64 48. Model settings that admins saved are sealed with it. To rotate it:

  1. Set the new value as AIDY_SECRET and the old one as AIDY_PREVIOUS_SECRET, and deploy. The new secret seals; both unseal, and settings sealed with the old one are sealed again with the new one when first read.
  2. Once settings have been read (any GET /aidy/v0/settings or run does it), remove AIDY_PREVIOUS_SECRET.

Embedded, pass the list: secret: [newSecret, oldSecret]. If aidy has none of the secrets the settings were sealed with, the settings routes answer 503 settings_unreadable and runs fail, until the secret is back or an admin calls DELETE /aidy/v0/settings, after which the configured chain applies again.

Terminal window
docker run -d --name aidy -p 8080:8080 --env-file aidy.env ghcr.io/aidy-dev/aidy-server:v0.2.0

Images are tagged with the release (v0.2.0) and latest. The image runs aidy-server serve as the node user on port 8080 and has a health check on /healthz. aidy.env holds the variables above; for AIDY_KNOWLEDGE_DIR or @path values, mount the files and point the variables at them.

To build on your own base image (an internal registry, say), pass --build-arg BASE_IMAGE=… --build-arg AIDY_VERSION=0.2.0 to the Dockerfile in packages/server.

aidy ships no Helm chart. Run the image as a Deployment with its variables from a Secret, and probe /healthz:

containers:
- name: aidy
image: ghcr.io/aidy-dev/aidy-server:v0.2.0
ports: [{ containerPort: 8080 }]
envFrom: [{ secretRef: { name: aidy-env } }]
readinessProbe: { httpGet: { path: /healthz, port: 8080 } }

Keep AIDY_SECRET, AIDY_PREVIOUS_SECRET, AIDY_DATABASE_URL, AIDY_SIGNING_KEY and AIDY_MODELS (it holds API keys) in the Secret. Runs survive a client disconnect, and a replica that stops lets its lease expire. With two or more replicas, route MCP sessions to one replica (Several instances).

Several aidy instances can share one database: approvals and deferred tasks are consumed exactly once, and runs hold a lease so two instances never drive one thread. Two things live in the memory of one instance:

  • MCP sessions and their pending elicitations stay on the instance that opened them. Route every request that carries one Mcp-Session-Id to the same instance (sticky sessions, or sessionAffinity: ClientIP on a Kubernetes Service), or run one instance. A request that reaches another instance gets 404 session_not_found, and the client opens a new session.
  • Model rests are kept per instance, so each instance learns on its own that an endpoint is failing.

A run outlives its response only while the instance lives. On Workers it is registered with ctx.waitUntil, which ends with the request’s lifetime limits, and every isolate is its own instance. A Worker that hosts aidy should therefore route each user (or each thread) to a Durable Object that owns the aidy instance: the object keeps running while a run streams, and its MCP sessions and rests stay in one place. The aidy site does this with one Durable Object per visitor.

import { DurableObject } from 'cloudflare:workers';
import { createAidy, SqlStore, type Aidy } from '@aidy-dev/core';
import { importSigningKey } from '@aidy-dev/spec/delegation';
import { d1Driver } from '@aidy-dev/sql/d1';
export class AidyObject extends DurableObject<Env> {
#aidy?: Promise<Aidy>;
fetch(request: Request) {
this.#aidy ??= importSigningKey(JSON.parse(this.env.AIDY_SIGNING_KEY)).then((signingKey) =>
createAidy({ /* url, host, models … */ signingKey, secret: this.env.AIDY_SECRET, store: new SqlStore(d1Driver(this.env.DB)) }),
);
return this.#aidy.then((aidy) => aidy.fetch(request, this.ctx));
}
}
export default {
async fetch(request: Request, env: Env) {
const user = await userIdOf(request); // your session lookup
return env.AIDY.get(env.AIDY.idFromName(user)).fetch(request);
},
};

Bind the class as a Durable Object (AIDY here) in wrangler.jsonc. Requests of one user then reach one object, and so do the MCP requests of that user’s sessions.

Send these paths on your product’s origin to aidy, unchanged:

Path Purpose
/aidy/v0/* The HTTP API and AG-UI streams
/mcp MCP over streamable HTTP
/skill.md, /llms.txt Generated agent documents
/.well-known/aidy-keys.json aidy’s public keys
/.well-known/oauth-protected-resource/mcp Only with AIDY_MCP_AUTHORIZATION_SERVERS

Runs stream Server-Sent Events, so turn off response buffering and allow long reads. With nginx:

location ~ ^/(aidy/v0/|mcp$|skill\.md$|llms\.txt$|\.well-known/(aidy-keys\.json|oauth-protected-resource/mcp)$) {
proxy_pass http://aidy:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_read_timeout 1h;
}

Forward the Authorization header and cookies untouched: aidy authenticates each request by calling your identity operation with it.

To serve aidy under a prefix such as /assistant, set AIDY_BASE_PATH=/assistant and AIDY_URL=https://console.example.com/assistant, and proxy the prefix. Clients then use that prefix as their baseUrl.

  • aidy check --openapi https://console.example.com/openapi.json passes.
  • GET /aidy/v0/catalog with a user token lists that user’s operations.
  • A write through the dock shows an approval card, and your API logs actor = aidy with the approval id.
  • /skill.md and /llms.txt render, and claude mcp add connects (MCP clients).