Setting up the copilot

The copilot — Ortha CMS AI in the admin — is off by default, because a hosted backend sends workspace content to a third party.

Turn it on

COPILOT_ENABLED=true

# At least one backend. Setting its key / URL is what registers it.
ANTHROPIC_API_KEY=sk-ant-…
# …or any OpenAI-wire endpoint (Ollama, vLLM, LiteLLM, OpenAI, Azure…)
COPILOT_OPENAI_BASE_URL=http://localhost:11434/v1
COPILOT_OPENAI_MODELS=<model-id>
COPILOT_OPENAI_API_KEY=

• Once on, the Ask Ortha AI launcher appears under the admin’s work area, at its right end, inside any workspace (⌘J / Ctrl+J), for users with copilot:use.
• COPILOT_ENABLED=true with no backend registered fails at boot.
• Off means absent: no /api/copilot route, no chat, no Agents view, no Skills page. The MCP endpoint is unaffected — the tool registry stays bound.
• Every variable per backend: model providers.

There is no “which provider” setting

• A backend is registered only when configured, in the order plugins.ts lists them.
• The first registered one serves a run that names none, and is what the model picker opens on.
• There is no defaultProvider variable — a name in a variable could be misspelt or point at nothing.

Registered names: claude and openai in a generated app; claude and ollama in the monorepo’s own app.

Check it from the command line

The copilot routes are session-authenticated admin routes. Sign in first:

curl -c cookies.txt -X POST https://cms.example.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"editor@example.com","password":"…"}'

Which backends are live (copilot:use):

curl -b cookies.txt https://cms.example.com/api/copilot/models

{
    "items": [
        { "provider": "claude", "model": "<model-id>" },
        { "provider": "openai", "model": "<model-id>" }
    ]
}

A 404 here means COPILOT_ENABLED is off.

Start a run — the answer streams back as Server-Sent Events:

curl -N -b cookies.txt -X POST https://cms.example.com/api/copilot/runs \
  -H 'X-Workspace-Id: 7f1c…' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Which articles are missing a summary?","skills":[{"name":"house-style"}]}'

event: run-started
data: {"type":"run-started","conversationId":"…","runId":"…","messageId":"…"}

event: tool-call
data: {"type":"tool-call","id":"call_1","name":"admin_content_search","input":{"typeName":"article"}}

event: tool-result
data: {"type":"tool-result","id":"call_1","name":"admin_content_search","ok":true,"durationMs":41,"summary":"…"}

event: text-delta
data: {"type":"text-delta","text":"Three articles have no summary: …"}

event: done
data: {"type":"done","stopReason":"end","usage":{"inputTokens":5120,"outputTokens":312}}

Other events: tool-permission-request (a write is waiting for Allow/Don’t allow), proposal (a recorded change), error. The route requires copilot:use, workspace membership and, as a cookie write, an allowed Origin or none.

The run ceilings

Three limits bound a run; a fourth bounds each model response.

• Each must be a positive number; 0 or negative fails at boot.
• Cache reads don’t count. The token ceiling is checked between steps, so a run can overshoot by one call.
• A step is one model call plus the tools it asks for — maxSteps bounds depth, not width. Small local models need more steps.
• A run that stops reports stopReason: max-steps, timeout, max-tokens, max-output-tokens, or quota (see usage limits). The chat shows “This answer is incomplete”.

export function copilotConfig(): AppCopilotConfig {
    return {
        enabled: readFlag('COPILOT_ENABLED', false),
        maxOutputTokens: readPositiveInt('COPILOT_MAX_OUTPUT_TOKENS', 8192),
        limits: { maxSteps: 60, wallClockMs: 600_000, maxTotalTokens: 800_000 },
        providers: defined({ /* … */ })
    };
}

Usage limits

The ceilings bound how big one run may get. Four more limits (since 0.11.0) bound how much the copilot may be used. Each is off until you set it.

• Empty is no limit; 0 or a negative number fails at boot.
• Tokens are counted the way COPILOT_MAX_TOTAL_TOKENS counts them.
• Spend is recorded either way, in the copilot_usage table — so a quota switched on at noon already knows the morning. The counts live in Postgres, so they hold across instances and survive a restart.
• A run is checked before it starts. A refusal is a 429 and nothing is stored — no thread, no message (the codes are in errors).
• The daily quotas are checked again between steps. A run that spends what is left stops with stopReason: "quota" and keeps its partial answer, and the model is told so a later “continue” resumes it. Like the token ceiling, it can overshoot by one model call.
• A daily quota below one run’s token ceiling is allowed, with a warning at boot: a long run will be stopped by the quota before its own limit.

In the admin, when a person has a daily quota, a thin meter under the chat box shows their use today. Once it is spent — theirs or the workspace’s — the box refuses to send, keeps the text typed, and says when sending works again, in the reader’s own clock. A member sees their own figure; of the workspace’s quota they see only whether it is spent (GET /api/copilot/usage).

quotas: { userDailyTokens: 2_000_000, runsPerMinute: 10, maxConcurrentRuns: 2 },

Where the settings live

Provider settings live in the app, not the copilot packages — the plugin is adapter-agnostic. Two backends of one kind are two entries (ollamaFast, ollamaBig).

Per-run routing

The first registered provider serves any run that names none — in practice MCP-initiated work, API calls and tests, since the admin’s picker always sends its choice. To route per run, pass a resolver:

// apps/server/src/plugins.ts
CopilotPlugin({
    providers: copilotProviders(config),
    // (ctx: { workspaceId, userId }, providers) => a registered provider name
    resolve: (ctx) => (bigWorkspaces.has(ctx.workspaceId) ? 'claude' : 'openai'),
    config: config.plugins.copilot
});

A model the user picked explicitly still wins.

Who can use it

• copilot:use — held by every role (Admin, Contributor, Viewer).
• Beyond that a run holds the user’s own permissions. There are no separate copilot grants and no per-workspace copilot policy.
• Skills are the only per-workspace setting — authored by Admins (copilot:skills:manage). See skills.

Run it locally with no API key

There is no scripted “offline” backend — the fake provider is a private test fixture. Run a local model through the OpenAI-wire adapter instead:

ollama serve
ollama pull <model-id>

COPILOT_ENABLED=true
COPILOT_OPENAI_BASE_URL=http://localhost:11434/v1
COPILOT_OPENAI_MODELS=<model-id>
COPILOT_OPENAI_API_KEY=

That exercises the chat, the permission prompt and the change cards end to end. The adapter assumes tool calling, streaming and a 32K context — declare less for a small model; see model providers.