[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10,"_11":12},"actionData","errors","root",{"_228":-5,"_231":232,"_233":234},"routes/shell",{"_40":41,"_227":-5,"_228":-5,"_229":230},"routes/repo",{"_33":-7,"_34":35,"_36":37,"_38":39,"_40":41,"_42":31,"_43":31,"_44":31,"_45":31,"_46":31,"_47":31,"_48":49,"_50":49,"_51":31,"_52":-7,"_53":-7,"_54":55,"_56":57,"_58":59,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":68},"routes/repo.blob",{"_13":14,"_15":16,"_17":18,"_19":20,"_21":14,"_22":23,"_24":-5,"_25":26,"_27":28,"_28":29,"_30":31,"_32":14},"ref","ee24630cf0379d63d6fff8bbd2ad6ff7cc8dd3f0","path","docs/self-hosting.md","oid","ef12d5192fec8ca391a5bedabb6ab88b2ebcdf58","size",44722,"commit","mounts",[],"source","plain",{"_13":14,"_15":16},"kind","text","# Self-hosting\n\nThis guide is for operators evaluating Chopin on infrastructure they control.\nChopin is an experimental research prototype, not a supported production\nservice. Its current deployment model is one application process, one\nPostgreSQL database, one exact public origin, and a GitHub App registered for\nthat origin.\n\n## Support boundaries\n\n- GitHub.com is the only supported GitHub host.\n- Chopin must be served at the root of one origin. Subpath hosting is not\n supported.\n- HTTPS is required except for a loopback development origin.\n- The application, API, MCP endpoint, and WebSocket share one origin and one\n internal port.\n- One active Chopin process may write to a database. Horizontal application\n scaling and zero-downtime rolling deployment are not supported.\n- PostgreSQL 17 is the version used by the repository and browser tests. Other\n versions are not covered by the project test suite.\n- Database migrations are forward-only. There is no automated schema rollback.\n- Restarting the application signs every browser out and releases hosted agent\n ownership. Documents, transcripts, decisions, background jobs and artifacts,\n research request staging, child documents, and implementation state remain.\n In local mode (see below), the returning browser can restore the same login\n without repeating device-flow sign-in; it still gets a new session and does\n not reclaim Planner ownership.\n\n## Choose the access policy first\n\nEvery browser user authenticates through the GitHub App. Two optional admission\nlists decide who may enter the instance:\n\n- `GITHUB_ALLOWED_USERS` contains comma-separated GitHub logins.\n- `GITHUB_ALLOWED_ORGANIZATIONS` contains comma-separated organizations whose\n active members are admitted.\n- The lists are case-insensitive and form a union.\n- Leaving both lists empty admits every verified GitHub user.\n\nAdmission does not grant repository access. Browser routes and WebSockets also\nrequire the repository to be present in a GitHub App installation available to\nthe user. Pull access permits viewing; push or administration access permits\ncreation, editing, and Planner invocation.\n\nChopin also registers `/mcp` unconditionally. It accepts a caller-supplied\nGitHub bearer token, applies the instance admission policy, and authorizes\nrepositories directly from that token. It does not require a GitHub App\ninstallation and can create documents or advance implementation lifecycle\nstate for callers with push or administration access. `AGENT=off` disables\nhosted agent turns and the background-job runner; it does not disable MCP.\n\nUse restricted admission for any internet-facing evaluation unless unrestricted\naccess is a deliberate choice. Protect the entire origin with TLS because MCP\nbearer tokens and browser sessions traverse it.\n\n## Choose and trust a harness\n\nChopin runs its hosted agent through `@ai-sdk/harness`. `HARNESS` selects one\nadapter from a code-owned map: the default is `copilot-sdk`, a host-process\nwrapper over `@github/copilot-sdk`; `pi` is a second reviewed adapter over\n`@ai-sdk/harness-pi`; and `atomic` embeds Atomic's headless SDK\n(`@bastani/atomic`) in the server process. Adding an adapter to that map is a\nreviewed trust decision, not a runtime plugin choice: an adapter's\n`builtinTools` and `supportsBuiltinToolFiltering` are self-declarations, and\nChopin's contract suite checks those declarations and the tools a session\nactually receives, but it cannot prove what the underlying runtime does\ninternally. Only adapters that ship in this repository and pass that suite\nbelong in `harnesses`.\n\nFor `copilot-sdk`, `direct` and `ai-gateway` are explicit `HARNESS_AUTH` modes\nthat may be used on any bind. A mode that could fall back to a subscription\nalready logged in on the host, such as `auto`, is refused at startup unless\n`SERVER_HOST` is loopback-only. The current `copilot-sdk` adapter still uses\neach owner's GitHub App user token and does not consume `HARNESS_AUTH`;\nsetting `auto` on loopback passes the startup guard but does not enable host\nlogin in that adapter.\n\n`HARNESS=pi` requires an explicit `HARNESS_AUTH`: unset is refused outright.\nPi's own documented modes are `auto`, `openai`, `anthropic`, `custom`, and\n`ai-gateway`; `direct` is not one of them and is refused. On a non-loopback\n`SERVER_HOST`, only `ai-gateway` is accepted, because every other mode can\nfall back to Pi's native `~/.pi/agent` login. `ai-gateway` reads\n`AI_GATEWAY_API_KEY` (or `VERCEL_OIDC_TOKEN`), `openai` reads `OPENAI_API_KEY`,\n`anthropic` reads `ANTHROPIC_API_KEY`, and `custom` forwards every `*_API_KEY`\nand `*_BASE_URL` variable. With `auto` on loopback, turns use the host\noperator's own Pi login; with an operator key, every admitted writer's turns\nbill that key.\n\nUnder `pi`, the channel owner supplies only the GitHub App user token; model\naccess comes from `HARNESS_AUTH`, not from the owner's Copilot entitlement.\nRepository reads still come from that GitHub token through Chopin's own host\ntools, never through Pi.\n\nUnder `pi`, `MODEL` is required and must be an ID from Pi's model catalog,\npreferably provider-qualified (for example `github-copilot/gpt-5.6-luna`).\nChopin's default, `gpt-6-luna`, is a Copilot ID that Pi does not recognize.\n`@ai-sdk/harness-pi` 1.0.148 fails the turn for an unknown ID (\"Harness 'pi'\nhas no model ... in its catalog\") instead of falling back to another model, so\nthe startup banner always names the model Pi runs.\n\nChopin patches `@ai-sdk/harness-pi` 1.0.148 so Pi's resource loader never reads\n`AGENTS.md` or `CLAUDE.md` context files from the session's working directory,\nits parent directories, or Pi's agent directory on the host. The change lives\nin `patches/@ai-sdk%2Fharness-pi@1.0.148.patch`; reapply or drop it when\nbumping `@ai-sdk/harness-pi`, and run the Pi contract suite\n(`apps/server/src/harness/pi.contract.test.ts`), which covers both behaviors.\n\n`@ai-sdk/harness-pi` 1.0.148 cannot return structured output itself, so\nChopin registers a result tool as an inline Pi extension. The tool runs inside\nPi and ends the turn (`terminate: true`), so the summary and research workers\nget their structured result without a follow-up model request. The adapter\nenables the tool only for a turn that requests structured output and blocks it\non every other turn. Prompt text, including quoted earlier chat, cannot enable\nit. The Pi contract suite (`apps/server/src/harness/pi.contract.test.ts`)\ncovers this against the real Pi agent loop; run it before bumping\n`@ai-sdk/harness-pi` or `@earendil-works/pi-coding-agent`.\n\n`HARNESS=atomic` runs Atomic 0.9.28 in the Chopin server process through its\nheadless SDK (`createAgentSession()`). It does not spawn the `atomic` CLI, use\nRPC mode, or substitute Atomic for Pi's runtime.\n\n**Choosing `HARNESS=atomic` gives the Planner shell and filesystem access as the\nserver process's user, on hosted instances as well as local ones.** Every Planner\nsession is a full Atomic session: Atomic's workflows, subagents, MCP, web access,\nIntercom, and default coding tools run beside Chopin's document tools, with the\noperator's Atomic extensions, skills, prompt templates, and context files. There is\nno separate flag; choosing the harness is the choice. Operators who do not want that\nshould use `copilot-sdk` or `pi`, whose Planner keeps the isolated, Chopin-tools-only\nboundary. Only the summary and research workers still run isolated Atomic sessions.\nSee [The atomic Planner](#the-atomic-planner) below and\n[Hosted agent](hosted-agent.md#full-atomic-planner) for the details.\n\n`HARNESS=atomic` requires an explicit `HARNESS_AUTH`, either `auto` or\n`ai-gateway`. Unset, `direct`, and every other value are refused at startup.\n\n- `auto` copies the host operator's Atomic login into memory when the first\n turn starts: `$ATOMIC_CODING_AGENT_DIR/auth.json` when that variable is set,\n then `$PI_CODING_AGENT_DIR/auth.json` for the legacy variable, otherwise\n `~/.atomic/agent/auth.json` over the legacy `~/.pi/agent/auth.json`.\n It also resolves provider keys from the process environment, such as\n `ANTHROPIC_API_KEY`, and ambient cloud credentials, such as an AWS profile or\n Google application default credentials. Because every admitted writer's turns\n would use the operator's own subscription or keys, `auto` is refused unless\n `SERVER_HOST` is loopback-only.\n- `ai-gateway` starts without stored credentials, reads `AI_GATEWAY_API_KEY`,\n and accepts only `vercel-ai-gateway` models. It is the only mode allowed on a\n non-loopback bind.\n\nThe adapter never writes credentials to disk. It reads the host login without a\nlock file, keeps refreshed OAuth tokens in memory, and neither reads nor writes\nAtomic's `models.json` or `models-store.json`.\n\nUnder `atomic`, `MODEL` is required and must name a `provider/model` from\nAtomic's catalog: for example `vercel-ai-gateway/anthropic/claude-sonnet-4.6`\nunder `ai-gateway`, or `github-copilot/gpt-6-luna` under `auto` with a GitHub\nCopilot login. An integration that passes Atomic a failed model lookup gets\nanother model without warning. This adapter looks the model up itself and\nfails the turn before any model request.\n\nStructured output uses the same approach as Pi: an inline Atomic extension\nregisters a terminating result tool, enabled only for a turn that requests\nstructured output and blocked on every other turn. The tool records the calling\nmodel's own arguments. The adapter does not use Atomic's\n`createStructuredOutputTool`, which infers the answer again with a second model\ncall. The Atomic contract suite\n(`apps/server/src/harness/atomic.contract.test.ts`) covers isolation, model\nresolution, host tools, structured output, and abort against Atomic's real\nagent loop. Run it before bumping `@bastani/atomic`.\n\nAtomic caveats:\n\n- Atomic's SDK defaults suit a local coding agent, not Chopin. By default it\n enables its shipped packages, including a mandatory Intercom, and its coding\n tools. It discovers host resources, gives turns without instructions a\n coding-agent system prompt, and saves tool results over 50,000 characters to a\n temporary file. For the isolated worker sessions the adapter overrides each\n default and fails closed on the ones it can observe, but a new Atomic release\n can add a default the suite does not check. Planner sessions deliberately keep\n those capabilities.\n- Sessions live only in memory. `doStop` returns a state the adapter refuses to\n resume, so a session never survives a restart. Chopin does not resume\n harness sessions.\n- Harness-level compaction, suspending a turn, and supplied harness skills are\n unsupported. A Planner session's own resource discovery does load Atomic\n skills. Atomic's automatic retries remain on.\n- Under `auto`, refreshing an OAuth token in memory can rotate the refresh token\n stored by the host CLI, which may then ask the operator to sign in again.\n `auto` also runs `!command` API-key entries in `auth.json` to resolve them.\n- There is no per-session credit limit like Copilot's, so a worker's\n `maxAiCredits` does not apply. Use the provider's spend limits.\n- `@bastani/atomic` adds more than 250 MB of installed dependencies on Linux\n x64, including glibc and musl native modules and the embedded PostgreSQL\n that only Atomic workflows use. Expect a larger image.\n- Atomic depends on `typebox` 1.3.27 while Chopin pins 1.3.7. Host tool schemas\n pass to Atomic as plain JSON Schema, so the two versions never meet.\n\nFor a reviewed adapter that consumes a shared operator key, every admitted\nwriter's turns would bill that key. Chopin adds no billing quotas of its own in\nthis revision, across jobs or users; use the model provider's spend limits and\nusage alerts. A Copilot credit limit applies to one harness session, including all\nturns of its job stage, not as a platform-wide budget; see\n[Background jobs](background-jobs.md#executor-owned-limits).\n\n### The atomic Planner\n\nA Planner session's working directory comes from one place: a `checkout` path\nsupplied through the MCP\n[`invoke_planner`](local-agent-mcp.md#hand-an-instruction-to-the-planner) tool.\nChopin checks it with Git and compares `origin`'s owner/repository to the\ndocument's repository, ignoring case and the remote host spelling (so SSH host\naliases work). A mismatching or missing path refuses the invocation before\nanything is posted. A verified path is remembered for that document until the\nserver process exits; nothing is written to storage. Every later Planner session\nfor the document, whether started from the browser or through MCP, re-verifies\nthe remembered path before using it. The check establishes repository\ncoordinates, not remote-host authenticity, and it does not confine the shell.\n\nWithout a remembered checkout that still verifies, the session runs in a directory Chopin keeps for that document alone under its per-user state\ndirectory (`$XDG_STATE_HOME/chopin/planner/`, defaulting to\n`~/.local/state`; `~/Library/Application Support/Chopin/planner` on macOS;\n`%LOCALAPPDATA%\\Chopin\\planner` on Windows), with mode `0700`. It is never shared\nwith another document, keeps what the Planner and its workflows write there\nacross later sessions and server restarts, and is not placed in the shared\ntemporary directory. A symlink or file at that path is refused. The session has the\nsame tools either way; the Planner is told whether it is in a checkout or in an\nempty directory without repository files, and its repository tools remain\navailable.\n\nAtomic input (`ask_user_question`, extension dialogs, and workflow-stage\nquestions) appears as shared Decisions instead of terminal dialogs, including\nworkflow run and stage labels. Unanchored batches append at the document's end.\nDialog text and written answers stay verbatim, bounded only by the document's\n256 KiB source limit and the shared-draft limits rather than the Planner's own\nquestion limits. A request nobody answers within 30 minutes expires: its cards\nstay in Decisions marked as expired, and Atomic receives no answer. Cancellation\nwithdraws pending cards; neither ever approves an action. See\n[Full Atomic Planner](hosted-agent.md#full-atomic-planner) for the mapping,\nresource loading, persistence, and workflow restart boundaries.\n\n`invoke_planner` itself is offered on every harness and in both authentication\nmodes. Other harnesses ignore its `checkout`: they neither verify nor use nor\nremember it.\n\n## Prerequisites\n\n- Docker for the application image, or Bun 1.4.2 for a source deployment.\n- A reachable PostgreSQL database and credentials with schema migration access.\n- A stable DNS name with TLS termination and WebSocket proxying.\n- Outbound HTTPS access to GitHub and the selected harness's model provider\n (the hosted Copilot service for `copilot-sdk`).\n- If `CONVERSATION_PLAN=on`, outbound HTTPS access to TypeSafe's Jev service\n (`api.typesafe.ai`) and a server-side `JEV_API_KEY`, separate from the Planner's\n harness credentials.\n- A GitHub App owned by the deployment.\n- At least one user with repository push or administration access.\n- For `copilot-sdk`, an active Copilot entitlement for each user who may own a\n hosted agent session. For `pi` or `atomic`, model credentials for the chosen\n `HARNESS_AUTH` mode instead.\n\n## Register the GitHub App\n\nCreate one GitHub App per deployment. Register the exact public origin:\n\n```text\nHomepage URL: \nCallback URL: /auth/github/callback\nSetup URL: /auth/github/setup\n```\n\nEnable expiring user authorization tokens, leave OAuth during installation\ndisabled, disable webhooks, and make the App installable on any account. Leave\ndevice flow disabled unless this deployment also uses local device-flow\nsign-in (below), which requires enabling it instead. The complete product\nuses these read-only repository permissions:\n\n```text\nContents: Read-only\nPull requests: Read-only\nChecks: Read-only\nCommit statuses: Read-only\nMetadata: Read-only (automatic)\n```\n\nOrganization admission additionally requires organization Members read access\nand owner approval on every admitted organization. See\n[Authentication](authentication.md) for the complete identity, installation,\nsession, and authorization model.\n\n## Runtime configuration\n\nStore production values in the deployment's secret manager or an owner-readable\nenvironment file outside the source tree. Do not bake `.env` or credentials into\nthe image.\n\n| Variable | Default | Meaning |\n| ------------------------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `STORAGE_DRIVER` | `postgres` | Storage adapter. `postgres` is currently the only accepted value. |\n| `DATABASE_URL` | required | `postgres:` or `postgresql:` connection URL. It is not printed by Chopin. |\n| `APP_ORIGIN` | required | Exact public origin, without credentials, path, query, fragment, or trailing slash. HTTPS is required unless the host is loopback. |\n| `GITHUB_APP_SLUG` | required | Lowercase slug from the App's public URL. |\n| `GITHUB_APP_CLIENT_ID` | required | OAuth client ID, not the numeric GitHub App ID. |\n| `GITHUB_APP_CLIENT_SECRET` | required (hosted) | OAuth client secret used for user-token exchange and refresh. Unused when `AUTH_MODE=local`. |\n| `GITHUB_ALLOWED_USERS` | empty | Comma-separated admitted GitHub logins. |\n| `GITHUB_ALLOWED_ORGANIZATIONS` | empty | Comma-separated organizations whose active members are admitted. |\n| `SESSION_ENCRYPTION_KEY` | required | Exactly 64 hexadecimal characters. Encrypts the hosted OAuth attempt cookie and derives a separate key for session credentials in PostgreSQL. Keep stable across releases and outside the database; replacing it invalidates hosted logins. Local mode requires the configured key but uses separate unpredictable, HttpOnly attempt and browser-binding cookies. |\n| `AUTH_MODE` | `hosted` | Set `local` for loopback device-flow sign-in with persisted credentials (see [Authentication](authentication.md#local-device-flow-sign-in)). Any other value fails startup. |\n| `CHOPIN_LOCAL_CREDENTIALS_DIR` | platform default | Local mode only. Overrides the plaintext-fallback credential directory (default `~/.config/chopin` on Linux, `~/Library/Application Support/Chopin` on macOS, `%APPDATA%\\Chopin` on Windows). Must resolve outside the repository and process working directory. |\n| `SERVER_HOST` | `127.0.0.1` | Source-process bind address. The image sets `0.0.0.0`, which local mode refuses. A `HARNESS_AUTH` mode that falls back to a host-logged-in subscription is refused unless this stays loopback-only. |\n| `PORT` | `8787` | Source-process HTTP and WebSocket port. The supplied image and health check expect internal port 8787. |\n| `MODEL` | `gpt-6-luna` | Model requested for hosted agent sessions. Required under `HARNESS=pi` and `HARNESS=atomic`; under `atomic` it must be `provider/model` from Atomic's catalog. |\n| `HARNESS` | `copilot-sdk` | Adapter name selected from Chopin's harness map (`copilot-sdk`, `pi`, or `atomic`). An unknown name refuses at startup. `atomic` gives every Planner session shell and filesystem access as the server process's user, hosted instances included; see [Choose and trust a harness](#choose-and-trust-a-harness). |\n| `HARNESS_AUTH` | unset | Auth mode forwarded to the selected adapter. For `copilot-sdk`, `direct` and `ai-gateway` are allowed on any bind and `auto` requires a loopback-only `SERVER_HOST`; the adapter does not otherwise consume it. For `pi`, it is required: `auto`, `openai`, `anthropic`, and `custom` require a loopback-only `SERVER_HOST`, only `ai-gateway` is allowed otherwise, and `direct` is always refused. For `atomic`, it is required and must be `auto`, which requires a loopback-only `SERVER_HOST`, or `ai-gateway`; every other value is refused. |\n| `HARNESS_EXTENSIONS` | unset | Extension or package paths every atomic Planner session loads, as Atomic's `--extension` flag would, separated by the platform path delimiter (`:`, or `;` on Windows). A package's extensions, skills, and workflows all register. Each path must be absolute and exist; any other harness refuses the variable at startup. Background workers never load them. The code runs in the server process as its user. |\n| `AGENT` | on | Set exactly `off` to prevent hosted agent turns, disable the entire background-job runner, and avoid Copilot CLI startup. |\n| `BACKGROUND_JOBS` | on | Set exactly `off` to disable background job scheduling. `AGENT=off` disables the entire runner. |\n| `WEB_RESEARCH` | on | Set exactly `off` to disable new public-web research while retaining durable requests, artifacts, and other jobs. |\n| `COPILOT_CLI_PATH` | automatic | Advanced override for the Copilot CLI executable. Applies only to the `copilot-sdk` adapter. |\n| `CONVERSATION_PLAN` | off | Set exactly `on` to enable experimental conversation-derived cards. Interpretation runs independently of `AGENT`; Planner jobs still obey the agent and job settings. |\n| `JEV_MODEL` | `jev-latest` | Model alias for conversation interpretation. Independent of the hosted Planner's `MODEL`. |\n| `JEV_TIMEOUT_MS` | `30000` | Per-request interpretation timeout in milliseconds, an integer between 100 and 60000. |\n| `JEV_API_KEY` | required when enabled | Server-side Jev API key. Required at startup when `CONVERSATION_PLAN=on`; never send it to the browser. |\n\nSee [Background jobs and workers](background-jobs.md) for the combined\n`AGENT`, `BACKGROUND_JOBS`, and `WEB_RESEARCH` behavior and recovery model.\n\nConversation-derived cards default to off. When enabled, interpretation sends\ncurrent and recent Chat messages and selected decision context to TypeSafe's Jev\nservice. It uses `JEV_API_KEY` and `JEV_MODEL` independently of the Planner's\nprovider and credentials; `AGENT=off` does not disable it.\n\nThe same flag enables independent external-research suggestions in Chat. Their\nshared briefs can be synthesized by the `research-brief@1` background worker under\nthe existing Planner owner; this uses the configured harness provider, separately\nfrom Jev. A self-contained source excerpt is the fallback when synthesis is\nunavailable. Actual research starts only after a writer accepts the current shared\nbrief and the execution capability is enabled. See\n[Research offers from Chat](conversation-research.md).\n\nThe supplied Compose file forwards `CONVERSATION_PLAN`, `JEV_MODEL` and\n`JEV_API_KEY` from the deployment environment. It uses the server's default\n30-second interpretation timeout. To override `JEV_TIMEOUT_MS`, configure it\nexplicitly in the service environment; the Compose file does not forward an\nunset optional timeout as an empty value.\n\nGenerate the encryption key with:\n\n```bash\nopenssl rand -hex 32\n```\n\nThe image expects to listen on internal port 8787. Do not override `PORT` in the\nsupplied image without also replacing its health check and container routing.\n\n## Deploy the Docker image\n\nThe `Dockerfile` builds the browser client and one runtime image. The Bun server\nserves static assets, HTTP routes, `/mcp`, and `/ws` from the same process. Its\ndefault command applies migrations before starting the server and runs as the\nunprivileged `bun` user.\n\nBuild an image from a reviewed commit:\n\n```bash\ndocker build --tag chopin:local .\n```\n\nCreate an environment file such as `/etc/chopin/chopin.env`:\n\n```dotenv\nSTORAGE_DRIVER=postgres\nDATABASE_URL=postgresql://:@:5432/\nAPP_ORIGIN=https://chopin.example\nGITHUB_APP_SLUG=\nGITHUB_APP_CLIENT_ID=\nGITHUB_APP_CLIENT_SECRET=\nGITHUB_ALLOWED_USERS=\nGITHUB_ALLOWED_ORGANIZATIONS=\nSESSION_ENCRYPTION_KEY=<64-hex-character-key>\nAGENT=on\nMODEL=gpt-6-luna\nHARNESS=copilot-sdk\nBACKGROUND_JOBS=on\nWEB_RESEARCH=on\n```\n\nRestrict that file to the deployment account, then start the image behind a\nsame-host reverse proxy:\n\n```bash\ndocker run --detach \\\n --name chopin \\\n --restart unless-stopped \\\n --env-file /etc/chopin/chopin.env \\\n --publish 127.0.0.1:8787:8787 \\\n chopin:local\n```\n\nIf the reverse proxy is another container, attach both containers to a private\nnetwork instead of publishing the application port. Ensure the database address\nin `DATABASE_URL` is reachable from the application container.\n\n### Reverse proxy requirements\n\nThe proxy must:\n\n- terminate TLS for the exact `APP_ORIGIN`;\n- forward the original `Host` and `Origin` headers;\n- proxy WebSocket upgrades on `/ws`;\n- proxy `/mcp` without removing its `Authorization` header;\n- serve Chopin at `/`, not below a path prefix; and\n- redirect alternate hosts to the canonical origin before application traffic.\n\nChopin derives OAuth callbacks from `APP_ORIGIN`, never from incoming `Host` or\nforwarded headers. A proxy cannot repair a mismatched configuration after the\nprocess starts.\n\n## Checked-in Compose files\n\nThe checked-in Compose files support repository development and the project's\nCoolify deployment; they are not a complete generic production stack.\n\n`compose.yaml` publishes no host ports, uses a fixed internal development\ndatabase credential, and includes Coolify late-binding variables. The local\ncommands merge `compose.local.yaml`, which currently publishes application port\n8787 and PostgreSQL port 5432 on every host interface:\n\n```bash\nbun run db:up # start only PostgreSQL for source development\nbun run docker:up # build and start the application and PostgreSQL\n```\n\nUse those commands only on a trusted, firewalled development machine. Do not\nattach `compose.local.yaml` to an internet-facing deployment. Both\n`bun run db:down` and `bun run docker:down` tear down the whole Compose project.\n\nCoolify supplies the public proxy and can substitute `SERVICE_NAME_DB` and\n`SERVICE_FQDN_APP`. Configure `APP_ORIGIN` as\n`https://${SERVICE_FQDN_APP}` and provide all GitHub, admission, model, and\nencryption values as runtime variables. Preview-specific late-binding and\ncredential isolation are described in [PR preview testing](preview-testing.md).\n\n## Deploy from source\n\nA source deployment must build the client, apply migrations, and start the\nserver as three distinct operations:\n\n```bash\nbun install --frozen-lockfile\nbun run build\nbun run migrate\nexec bun apps/server/src/main.ts\n```\n\nAll runtime configuration, including the GitHub App values, is required by the\nmigration command. `bun run start` starts the server but does not build the\nclient or migrate the database. A missing client build allows the API process to\nstart while the browser route returns 404.\n\nRun the direct server command under a process manager that restarts it after any\nunexpected exit. Some fatal runtime paths drain successfully and exit with code\nzero, so a policy equivalent to `Restart=on-failure` is insufficient.\n\n## Local device-flow sign-in\n\n`AUTH_MODE=local` is a single-machine mode for evaluating Chopin without an\noperator-managed GitHub App client secret. It is not an alternative deployment\ntopology: it requires a loopback `SERVER_HOST` and `APP_ORIGIN`, so it cannot\nbe reached from another machine, and it is incompatible with the Docker image,\nwhich sets `SERVER_HOST=0.0.0.0`. Run it from a source checkout:\n\n```bash\nbun install --frozen-lockfile\nbun run build\nAUTH_MODE=local APP_ORIGIN=http://127.0.0.1:8787 GITHUB_APP_SLUG= \\\n GITHUB_APP_CLIENT_ID= SESSION_ENCRYPTION_KEY=<64-hex-character-key> \\\n DATABASE_URL= bun run migrate\nAUTH_MODE=local APP_ORIGIN=http://127.0.0.1:8787 GITHUB_APP_SLUG= \\\n GITHUB_APP_CLIENT_ID= SESSION_ENCRYPTION_KEY=<64-hex-character-key> \\\n DATABASE_URL= exec bun apps/server/src/main.ts\n```\n\n`GITHUB_APP_CLIENT_SECRET` is not read in this mode. Enable device flow on the\nApp instead of the client-secret authorization-code flow described above, and\nkeep expiring user authorization tokens enabled. The browser shows GitHub's\ndevice code, persists the resulting credential to the OS credential store or,\nwith explicit consent, a local plaintext file, and restores that login after a\nrestart without a fresh device-flow prompt. See\n[Local device-flow sign-in](authentication.md#local-device-flow-sign-in) for\nthe complete flow, the plaintext-consent warning text, file permissions, and\nthe restart-restore and logout model.\n\nLocal logout deletes the persisted credential; it does not revoke the GitHub\nApp authorization, because device-issued refresh tokens can be refreshed\nwithout the client secret but GitHub's revocation endpoint requires it. Remove\nthe App from **Settings > Applications** on GitHub to revoke it there.\n\n## First-start smoke test\n\nStartup validates configuration, database connectivity, migration history, the\nexclusive writer lease, and the configured harness (unknown `HARNESS`, or a\nhost-login `HARNESS_AUTH` fallback on a non-loopback bind, refuse before the\nprocess serves traffic). It does not fully validate the GitHub App, Copilot\nentitlement, model, or lazy Planner runtime.\n\nAfter the first deployment:\n\n1. Confirm the process reports the intended restricted or unrestricted admission\n policy.\n2. Complete GitHub sign-in and return to the exact configured origin.\n3. Install the App on one non-sensitive test repository.\n4. Confirm the picker lists only expected installations and repositories.\n5. Create a channel with a user who has push or administration access.\n6. Open the channel in a second browser and verify presence and live edits.\n7. Send one `@chopin` request to verify model access (the owner's Copilot\n entitlement for `copilot-sdk`, or the `HARNESS_AUTH` credentials for `pi` or\n `atomic`)\n and the hosted agent runtime.\n8. Connect a local coding agent and call `list_documents` if MCP is part of the\n deployment's intended surface.\n\nThe image health check calls `/api/session`. It confirms HTTP liveness but does\nnot prove that a browser bundle is present, a new database transaction can\ncomplete, GitHub is reachable, or the Planner can start.\n\n## Operations\n\n### Backups and restore\n\nPostgreSQL is the durable system of record. Back up the complete database with\nthe database provider's consistent backup mechanism; copying only selected\ntables or the application container is not sufficient. Regularly test restore\ninto an isolated database before relying on the backup.\n\nStop Chopin before replacing a database from a backup. Starting against the\nrestored database validates migration checksums and acquires a new writer lease.\nBrowser sessions and Planner ownership are cleared at startup.\n\n### Upgrades\n\n1. Back up the database and retain the currently deployed image.\n2. Stop the existing application process.\n3. Start the new image against the same database; its entrypoint applies pending\n migrations before serving.\n4. Repeat the first-start checks after migrations or authentication changes.\n\nMigration files are checksummed once applied. Never edit an applied migration.\nBecause migrations are forward-only, returning to an older application image\nmay require restoring the pre-upgrade database rather than merely changing the\nimage tag.\n\n### Writer lease\n\nThe database holds one renewable `chopin:writer` lease. A second application\nprocess refuses startup. If the active process loses the lease, it drains and\nstops; fencing prevents an expired process from committing collaboration state.\nAllow the previous lease to expire before treating a failed host as safely\nreplaced.\n\n## Troubleshooting\n\n**OAuth returns to an error page.** Confirm `APP_ORIGIN`, the callback URL, and\nthe browser origin match exactly. A trailing slash or reverse-proxy hostname\nchange requires a configuration restart and corresponding GitHub App update.\n\n**No repositories appear.** Authorization and installation are separate. Check\nthat the App is installed on the repository, the signed-in user can access that\ninstallation, and any new permission is approved by the organization owner.\n\n**Organization admission is temporarily unavailable.** Confirm the App has\nMembers read access, the organization approved it, and the user has active\nmembership. GitHub outages and rate limits fail closed for new checks.\n\n**A second process refuses startup.** Another holder owns the database writer\nlease. Do not run two application instances against one database.\n\n**The process refuses startup with an unknown-harness or auth-mode error.**\n`HARNESS` names an adapter that is not in Chopin's harness map, or\n`HARNESS_AUTH` falls back to a host-logged-in subscription while\n`SERVER_HOST` is not loopback-only. Fix `HARNESS`/`HARNESS_AUTH` or bind the\nprocess to loopback for local-only use. See [Choose and trust a harness](#choose-and-trust-a-harness).\n\n**The UI returns 404 while APIs respond.** The source deployment did not build\n`apps/web/dist`, or the runtime image was assembled incorrectly.\n\n**The first model-backed action fails.** Check the invoking user's Copilot\nentitlement, the model, App permissions, repository write access, and Copilot\nCLI startup logs. Planner and research request execution validate these\ndependencies lazily.\n\n**MCP returns 401 or 403.** A 401 indicates an invalid or expired bearer. A 403\nindicates failed instance admission or a supplied Origin that differs from\n`APP_ORIGIN`. Repository authorization failures normally arrive as an MCP tool\nerror with reason `repository-forbidden`. See\n[Local agent MCP](local-agent-mcp.md) for client-specific guidance.\n\n## Related references\n\n- [Authentication](authentication.md)\n- [Hosted agent (Planner)](hosted-agent.md)\n- [Local agent MCP](local-agent-mcp.md)\n- [Storage](storage.md)\n- [Repository channels](channels.md)\n- [exe.dev development](exe-dev.md)\n","editable",false,"branch","documentNavigation","repo","githubnext/chopin","repoId","7d1a8ac3-35b0-4dea-85d4-06a980f3bada","ownerId","org:89615882","site","nexthub","private","admin","settings","maintainer","triage","starred","stars",0,"watchers","watching","pinned","notify","views",[183,184,185,186,187,188,189,190,191,192,193,194,195],"navigation",{"_54":55,"_139":140,"_141":142,"_143":144,"_145":146,"_147":148,"_149":150},"sources",[],"viewer","meta",{"_131":132,"_133":134,"_135":136,"_42":31,"_137":126,"_138":31,"_48":49,"_50":49},"branches",[73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130],"tags",[69,70,71,72],"cloneUrl","https://git.nexthub.sh/githubnext/chopin.git","color-controls-slice-1","color-controls-slice-2","color-controls-slice-3","color-controls-slice-4","Krzysztof-Cieslak-patch-1","Krzysztof-Cieslak-patch-2","Maggie/app-preview-toolkit","Maggie/ci-playwright-install-timeout","Maggie/collaborative-visual-decision","Maggie/design-audit","Maggie/generic-visual-decision-runtime","Maggie/impeccable-chopin-metadata","Maggie/jev-chat-product","Maggie/jev-composed-assessment","Maggie/native-document-layouts","Maggie/openui-composition-product","Maggie/openui-composition-trial","Maggie/planner-visual-authoring","Maggie/planner-visual-requests","Maggie/visual-selection-eval","artifacts/pr-419-live-preview-20261009","automation/pr-maintenance-state","automation/use-effect/callout-disabled-picker-8cf9e49ba5c09471","automation/use-effect/collaboration-options-ref-4e3a5a08a879a5ae","automation/use-effect/room-workspace-effective-access-a57d40866c71bed0","chore/bun-1.4.2","color-controls","color-controls-plan","comments","design-pr-assets","design/archived-decisions-badge","design/channel-route-remount","design/chat-decision-entry","design/conversation-analysis-markers","design/decision-evidence","design/settled-line-icon","dev/integration","diagram-step-controls","feat/liveapp-frontend-pilot","feat/local-experiments","feat/local-launcher-tracer","fix/autolink-mdx-crash","github-pills/2-pills","github-pills/3-hover-card","maggie/app-preview-toolkit","maggie/ci-playwright-install-timeout","maggie/collaborative-visual-decision","maggie/design-audit","maggie/generic-visual-decision-runtime","maggie/impeccable-chopin-metadata","maggie/jev-composed-assessment","maggie/native-document-layouts","maggie/openui-composition-product","maggie/openui-composition-trial","maggie/planner-visual-authoring","maggie/planner-visual-requests","maggie/visual-selection-eval","main","plain-text-fence-chrome","tokens/09-copy","wireframes/2-renderer","wireframes/3-planner","description","Let's compose rich plans together","owner","githubnext","section","","head","empty","pins",[165,166,167],"documents",{"_160":161,"_162":163},"code",{"_156":157,"_158":159},"automations",{"_153":154,"_155":-5},"delivery",{"_151":49,"_152":-5},"tag","04zvKQ8QOrDUF8TO1Ovz0Zy8_TT","releases","applications","workflows",3,"deployments","commits",1000,"changes",13,"counts",{"_164":163},"total",11,"issue",{"_168":158,"_170":181,"_15":158,"_172":182,"_52":174,"_175":31,"_176":174,"_177":159},{"_168":178,"_170":179,"_15":178,"_172":180,"_52":174,"_175":31,"_176":174,"_177":49},{"_168":169,"_170":171,"_15":169,"_172":173,"_52":174,"_175":31,"_176":174,"_177":163},"id","issues","name","Issues","filters",{},true,"saved","pinnable","count","tasks","Tasks",{},"Changes",{},{"_168":158,"_170":181,"_15":158,"_172":226,"_52":174,"_175":31,"_176":174},{"_168":178,"_170":179,"_15":178,"_172":225,"_52":174,"_175":31,"_176":174},{"_168":169,"_170":171,"_15":169,"_172":224,"_52":174,"_175":31,"_176":174},{"_168":221,"_170":222,"_15":221,"_172":223,"_52":31,"_175":31,"_176":174},{"_168":218,"_170":219,"_15":218,"_172":220,"_52":31,"_175":31,"_176":174},{"_168":153,"_170":216,"_15":145,"_172":217,"_52":31,"_175":31,"_176":174},{"_168":155,"_170":213,"_15":214,"_172":215,"_52":31,"_175":31,"_176":174},{"_168":151,"_170":211,"_15":151,"_172":212,"_52":31,"_175":31,"_176":174},{"_168":207,"_170":208,"_15":209,"_172":210,"_52":31,"_175":31,"_176":174},{"_168":141,"_170":205,"_15":141,"_172":206,"_52":31,"_175":31,"_176":31},{"_168":202,"_170":203,"_15":202,"_172":204,"_52":31,"_175":31,"_176":31},{"_168":199,"_170":200,"_15":199,"_172":201,"_52":31,"_175":31,"_176":31},{"_168":196,"_170":197,"_15":196,"_172":198,"_52":31,"_175":31,"_176":31},"decisions","Decisions",{},"changelog","Changelog",{},"roadmap","Roadmap",{},"Documents",{},"activity","Activity","insights",{},"Releases",{},"Deployments","automations/deployments",{},"Workflows",{},"discussions","Discussions",{},"goals","Goals",{},{},{},{},"groups","user","agents",[],"now",1794435276432,"sidebar","expanded"]