[{"_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","415101cb49f21e9a32b4cd5beee0852d2eea3972","path","docs/self-hosting.md","oid","ed0b7819cb20a79bba0995543e379b7397474e9d","size",20877,"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\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 and only shipped adapter is\n`copilot-sdk`, a host-process wrapper over `@github/copilot-sdk`. Adding an\nadapter to that map is a reviewed trust decision, not a runtime plugin choice:\nan adapter's `builtinTools` and `supportsBuiltinToolFiltering` are\nself-declarations, and Chopin's contract suite checks those declarations and\nthe tools a session actually receives, but it cannot prove what the\nunderlying runtime does internally. Only adapters that ship in this\nrepository and pass that suite belong in `harnesses`.\n\nWhen `HARNESS_AUTH` is set, `direct` and `ai-gateway` are explicit modes that\nmay be used on any bind. A mode that could fall back to a subscription already\nlogged 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`; setting\n`auto` on loopback passes the startup guard but does not enable host login in\nthat adapter.\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## 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 hosted Copilot service.\n- A GitHub App owned by the deployment.\n- At least one user with repository push or administration access.\n- An active Copilot entitlement for each user who may own a hosted agent\n session.\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 and\ndevice flow disabled, disable webhooks, and make the App installable on any\naccount. The complete product uses 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 | OAuth client secret used for user-token exchange and refresh. |\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 used for the encrypted OAuth attempt cookie, including its validated return path. |\n| `SERVER_HOST` | `127.0.0.1` | Source-process bind address. The image sets `0.0.0.0`. 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. |\n| `HARNESS` | `copilot-sdk` | Adapter name selected from Chopin's harness map. An unknown name refuses at startup. |\n| `HARNESS_AUTH` | unset | Auth mode forwarded to the selected adapter. `direct` and `ai-gateway` are allowed on any bind; `auto` and other possible host-login fallback modes require a loopback-only `SERVER_HOST`. The current `copilot-sdk` adapter does not consume it. |\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\nSee [Background jobs and workers](background-jobs.md) for the combined\n`AGENT`, `BACKGROUND_JOBS`, and `WEB_RESEARCH` behavior and recovery model.\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## 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 the owner's Copilot entitlement and the\n 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",1794479576859,"sidebar","expanded"]