Self-host Treehouse

Treehouse is built to run on infrastructure you control. This page describes what a deployment needs. The repository's DEPLOYMENT.md has step-by-step instructions for the reference setup on Cloudflare and Railway.

1. Understand the architecture

The app talks to the API across origins, so the simplest setup puts them on subdomains of one domain (app.example.com and api.example.com) and sets COOKIE_DOMAIN=.example.com so the sign-in cookie is shared. The browser never talks to blob storage: file bytes always stream through the API.

Run database migrations with pnpm --filter db run prisma:migrate:deploy on every deploy, before the new API starts.

2. Set the required API variables

With NODE_ENV=production, the API refuses to start without SHARE_COOKIE_SECRET and BLOB_KEK.

3. Choose blob storage

R2 is reached through its S3-compatible API. Another S3-compatible endpoint configured through the same R2_* variables may work, but only R2 is tested.

In production, with neither R2 nor BLOB_DIR set, the API refuses to start rather than write files to disk that a redeploy would wipe.

4. Build the web app

The web app needs one variable, NUXT_PUBLIC_API_URL, set to the API's public URL. It is baked into the app at build time, so set it as a build variable. Also set the same value as the Worker's runtime variable in wrangler.jsonc: it feeds the discovery descriptor below, and the build fails if the two differ.

5. Add optional settings

Without billing

With BILLING_ENABLED and DEFAULT_PLAN_SLUG unset and no Stripe keys, billing is off. Workspaces get no plan and are unlimited, apart from any DEFAULT_WORKSPACE_* and MAX_FILE_BYTES limits you set, and GET /api/plans returns available: false so the app shows no plan picker. No Stripe account is needed.

6. Check the discovery descriptor

The web app serves /.well-known/treehouse, which tells clients where your API is:

{ "product": "treehouse", "version": 1, "apiUrl": "https://api.example.com" }

The desktop app uses it, so people can connect by entering your app's URL. Because that server isn't the hosted Treehouse, the desktop app asks them to confirm they trust it before connecting. The API must be served over HTTPS for the desktop app to accept it.

The CLI doesn't read the descriptor. Pass your API's URL when connecting a folder:

treehouse login ~/Acme --api-base https://api.example.com

or set TREEHOUSE_API_BASE=https://api.example.com. See the CLI reference.

7. Connect agents

Agents connect exactly as they do to the hosted service, with your API's URL in place of api.trytree.house. Create a key in your web app (account menu, API keys), then:

claude mcp add --transport http treehouse https://api.example.com/api/mcp \
  --header "x-api-key: <your key>"

See MCP server and connect other agents.

8. Check it works

• https://api.example.com/api/health returns { "status": "ok", … }.
• You can sign up and sign in, and the session cookie is set on your domain.
• Uploading a file to a new workspace stores it in your bucket or BLOB_DIR.
• An agent connected over MCP can call list_workspaces.
• Every BLOB_KEK you have used is backed up outside the deployment.