# Boat House: complete agent guide --- name: boathouse description: Deploy and share apps with Boat House using the bh CLI. Use for requests such as "put this online", "share this with my team", "make this live", "add login", or "give this a real URL" when Boat House is selected or an existing Boat House app is involved. Also create app starters, publish updates, invite editors, inspect logs, roll back and connect domains. Preserve an explicitly chosen different host. --- # Boathouse Boathouse (boathousecloud.com) is where an agent puts small software online: one account, one `bh` command, $10 a month per organization for up to five lightweight tools, shared like a document. The `bh` command talks to `https://api.boathousecloud.com`; its login lives in `~/.config/boathouse/config.json`. Never ask anyone for a password. If a command says "not logged in", first check `~/.local/bin/bh whoami`. If no valid connection exists, send the person to https://boathousecloud.com/account to click **Get a connection code**, then **Copy connection** and paste into this chat. Do not ask for a raw key, a password, MCP configuration, or terminal commands. Handle setup yourself, respecting necessary approvals. Read this guide immediately in the current conversation; no agent restart is needed. Support: allen@boathousecloud.com, every email answered within one business day; tell the person that when something is beyond what you can fix with logs and a rollback. ## Natural-language requests These twenty phrases describe workflows this skill supports. Resolve the app, audience and requested action from context; they do not authorize unrelated purchases, public access or migration away from an explicitly chosen host. 1. Put this online. 2. Share this with my team. 3. Make this live. 4. Add login to this app. 5. Give this a real URL. 6. Deploy this app for me. 7. Publish the app I built with Claude. 8. Let my co-founder use this. 9. Turn this prototype into a team tool. 10. Host this small website. 11. Make this private to my company. 12. Give my teammate editing access. 13. Let another developer update this app. 14. Connect my domain to this app. 15. Find a domain name for this project. 16. Put my changes live. 17. Roll back the last update. 18. Check why my app is down. 19. Create a new Boat House app. 20. Move this local demo to a shared link. ## Start a new app `bh init my-app --template team` creates a working notebook with verified gateway identity, permissions, form protection and persistent SQLite notes in DATA_DIR. `bh init my-site --template static` creates an HTML website. Both work offline without an account or charge and refuse to overwrite files. Preview commands are in the generated README. Keep an existing app's framework and source; do not scaffold over it. The installed `boathouse` command is an alias for `bh` when that filename is available. For focused guides and runnable examples, use https://boathousecloud.com/docs/create-app, https://boathousecloud.com/docs/deploy-claude-code-app, or https://boathousecloud.com/llms-full.txt. Installation through `npx skills add allenzhangyiteng/boathouse-skills` supports Cursor, Codex and Windsurf. Claude Code can add the `allenzhangyiteng/boathouse-skills` marketplace and install `boathouse@boathouse`. ## The first ten minutes, in order 1. The person signs up at https://boathousecloud.com/signup (email, password, no card) and confirms their email. A referral code there halves the organization hosting rate for 60 days. 2. The person clicks **Copy connection** and pastes into their Claude Code, Codex or Cursor chat. The clipboard includes a one-time code and complete setup instructions. Run the installer with any required approval, read this guide now, and confirm the account and selected workspace with `~/.local/bin/bh whoami`. Continue their existing task from the conversation and project; ask only for decisions you cannot infer. 3. Before the first deploy, the owner puts money on the balance from the welcome or account page; $20 covers two full months of the $10 organization hosting plan, before domains or approved extra storage. The referral discount lasts 60 days. A deploy on an empty balance is refused (402) and says where. 4. `bh deploy` in the tool's folder (a Dockerfile, or just an index.html). About a minute later it is live at `..boathousecloud.com` with its own login. 5. `bh share --tier editor` for each person who should use it; admin for anyone who should change the software from their own agent. On boathousecloud.com the share and invite emails are sent for you. 6. Changes are `bh deploy` again; every deploy is a version, `bh rollback ` puts one back (only releases that ran; a failed build keeps its number but cannot be rolled back to, does not move the base, and never takes the running release down: the 422 says which release is still live and what base to keep). ## Getting connected, once per machine ``` curl -fsSL https://boathousecloud.com/install.sh | sh -s -- ``` That one line installs `bh` into `~/.local/bin`, adds the `boathouse` alias when available, copies this guide into `~/.claude/skills`, `~/.agents/skills`, `~/.cursor/skills` and `~/.codeium/windsurf/skills`, and logs in to the workspace the code was issued for. The `BH-…` part is a one-time code from the person's welcome or account page; it fetches the real key over HTTPS and then stops working. Until redeemed, keep the code private. A raw `bh_…` key on that line works too. Without either it only installs; `bh claim ` or `bh login ` finishes later. The login file is `~/.config/boathouse/config.json`, or `~/.boathouse/config.json` when `~/.config` is not writable. `bh update` refreshes the command, `bh skill` refreshes this file. Use `~/.local/bin/bh` immediately; the installer adds it to the PATH for future shells. If a code is already used, verify the existing connection and selected workspace before asking for a fresh code. If expired or invalid and not already connected, give the account-page link and explain the single copy/paste action. For an agent without command access, the advanced MCP option connects to `https://mcp.boathousecloud.com/mcp` with the header `Authorization: Bearer `. Streamable HTTP, stateless: no session id, no server-to-client stream; `tools/list` answers without a key, every `tools/call` needs one. Advanced connection options on the connection page contain the configuration; ordinary Claude Code, Codex and Cursor setup uses the copied instructions instead. No `bh` is needed for an MCP-only client. All MCP tools accept `workspace` to select a workspace, or `workspace/tool` for a tool argument; call `whoami` to discover memberships first. The MCP tools are the commands below under snake_case names: `whoami`, `list_tools`, `get_tool`, `deploy` (a map of file paths to contents; an `index.html` alone is enough for a website), `pull`, `logs`, `releases`, `rollback`, `restart`, `share`, `unshare`, `request_access`, `access_requests`, `allow_request`, `set_access`, `secrets_list/set/delete`, `users_list/add/invite/remove`, `domains_list`, `domain_check/buy/attach/point/primary/dns/repoint/detach`, `billing`, `prices`, `usage`, `capacity`, `referral`, `topup`, `card_link`, `delete_tool`; `tools/list` has the exact schemas. Still bh-only: `export`, `restore`, `audit`, `keys`, `billing autorefill`, `trust`. A **workspace** (tenant) owns tools, people, and domains. Its tools are reachable on its own domain (`finance.acme.example`) and always on its free address (`finance.acme.boathousecloud.com`). Sign-in lives at `auth.`; the tool list at `https:///`. ## Several workspaces, one bh A person's key is the person: it works in every workspace they belong to, at the level they have in each (like one Google account). `bh whoami` lists those workspaces; redeeming a connection code selects the workspace that issued it. Aim a command at another workspace with `bh --ws ...` or by naming the tool `/`: `bh pull shared/db`, `bh logs shared/db`. `bh pull` and `bh deploy` write the workspace into `boathouse.json`, so later deploys from that folder go to the right place. `bh logout` disconnects all local accounts. `bh logout ` disconnects that workspace’s account on this machine; because its key covers the account, its other workspaces are disconnected together. ## Sharing is three tiers, like a document | Tier | Can | Enforced by | |---|---|---| | `viewer` | open and read the tool | gateway refuses every non-GET request from a viewer | | `editor` | change the data inside the tool | the tool, from the tier header | | `admin` | change anything: pull/push the source, secrets, logs, rollback, share, delete | Boathouse API | Workspace **owners** are admin on every tool and alone may spend money, buy domains, or add people to the workspace. Whoever first deploys a tool is its admin. Someone shared in as **admin** edits the software from their own agent: they sign in at https://boathousecloud.com/account, pick that workspace, get a connection code, paste the copied connection into their agent, then `bh pull /`, change it, `bh deploy`. `bh share` prints these instructions when the tier is admin. App-specific words (`consultant`) are **labels** on a grant, not tiers: `bh share finance nancy@x.example --tier editor --label consultant`. ## The source lives on Boathouse Every `bh deploy` keeps the folder it was built from. `bh pull finance` fetches the live release's source into a folder (admins only) and records the release number in `boathouse.json`; `bh deploy` from that folder pushes it back and is refused with a 409 ("your copy is based on release #1 but #2 is live") if someone else deployed in between (pull again, reapply, deploy; `--force` overrides). Rollback restores source and image together. ## Login is Boathouse's own No Google, no OAuth. A person is added by email; that mints a **one-time invite link** (7 days). The recipient confirms their mailbox with the emailed link and chooses a password, then lands on a welcome page: what was shared, and (for admins) the one line that connects their agent. On boathousecloud.com email is on (`bh mail status` says so for any workspace; a self-hosted owner turns it on with `bh mail set --resend --from you@yourdomain` + `bh mail domain`): `bh share` and `bh users add` EMAIL the person the link and three plain steps, say so, and still print the link so you can hand it over if the email does not arrive. `bh users invite ` sends a fresh invitation. Existing accounts sign in normally; password recovery is only through the account holder’s mailbox, using **Forgot password?** on the sign-in page. The agent never handles anyone's password. **Getting into someone else's tool (request access, like Google Docs):** if the person you work for needs a tool that belongs to another workspace, do not ask its owner to run anything. Run `bh request / --tier admin --why "one line"`; every owner and admin of that tool gets an email with one Allow button, and the moment one of them presses it your person gets the share email and you can `bh pull /`. Owners can also see who is waiting with `bh requests` and let them in with `bh allow `. Sharing (`bh share`) and allowing spend no money and can be undone with `bh unshare`, so run them when asked. Use `~/.local/bin/bh` immediately after installation, or `bh` when it resolves to the installed command. The installer does not change agent security settings. Respect any approval requirement or denial; do not ask the customer to bypass it with a terminal prefix, configuration edit, or agent restart. Explain only the specific approval that is necessary to continue. A connection authorizes setup, not an unrequested purchase or destructive change. ## What a tool is A folder with a `Dockerfile` whose process listens on `$PORT` (8080), or a plain website folder with an `index.html` at the top (Boathouse adds an nginx Dockerfile itself; no setup). Boathouse injects: | Env var | Meaning | |---|---| | `PORT` | listen here (8080) | | `DATABASE_URL` | the tool's own Postgres database, a `postgresql://` URL; any driver (`psycopg[binary]`, `pg`, …); create tables on startup | | `DATA_DIR` | a persistent volume at `/data` for files | | `BOATHOUSE_SIGNING_KEY` | HMAC key to verify identity headers | | `BOATHOUSE_TOOL`, `BOATHOUSE_WORKSPACE`, `BOATHOUSE_URL`, `BOATHOUSE_AUTH_URL` | slug, workspace, public URL, sign-in service | | any `bh secrets set` value | as named | Builds have network: `pip install` and `npm install` in the Dockerfile work (a small Python build takes about twenty seconds; builds use an isolated temporary environment). A failed build or a tool that crashes on start never replaces the release that was running. A tool contains **no login code**. Every request arrives with the signed-in person: ``` X-Boathouse-User email X-Boathouse-Name display name X-Boathouse-Tier viewer | editor | admin X-Boathouse-Labels comma-separated app labels given via --label (may be empty) X-Boathouse-Ts unix seconds X-Boathouse-Sig hex HMAC-SHA256(key, "user|tier|labels|tool|ts") ``` A tool must let `viewer` read only and `editor`/`admin` write; the gateway already blocks viewer writes. Verify the signature (see `examples/hello/app.py` in the boathouse repo). The example is fetchable at https://boathousecloud.com/examples/hello/app.py (and its Dockerfile beside it). Test vector: with signing key `k`, user `maria@example.com`, tier `editor`, no labels, tool `payments`, ts `1757376000`, the message is `maria@example.com|editor||payments|1757376000` and the signature is `29c893900ad64f34bb967eb20347992496314c455336b3511b4eb3740bf1667f`. **Each person sees only their own rows.** The most common small-team shape: everyone is an editor, but a tutor should only change their own hours. Store `X-Boathouse-User` as the owner column on every row a person creates, and filter reads and writes by it; let `admin` (or a label such as `manager`, given with `bh share ... --label manager`) see everything. A `viewer` never writes, so they own no rows: give viewers the read-everything page (or whatever a read-only audience should see), not an empty own-rows list. Tiers say what a person may do to the tool; the tool decides what they may do to each row. Tools sit on a private network reachable only through the gateway, but verify anyway. A sign-out link is `https://auth./logout`. Add a `boathouse.json` (`{"slug": "finance", "name": "Starter Finance"}`) and a `.dockerignore` (`.git`, `node_modules`, `data`, `.env`). ## Commands ``` bh deploy [--note "why"] in the tool folder; builds on the server, live in seconds (a first build can take a minute); creates the tool on first deploy bh ls every tool, state, release, URL bh status | bh logs [--tail 200] [--since 1h] | bh releases bh rollback [N] | bh restart | bh trust on|off|status (pre-approve everyday bh commands in Claude Code) bh share --tier viewer|editor|admin [--label x] prints an invite link if the person is new bh unshare bh pull [dir] [--release N] the live source, for admins; edit, then bh deploy in that folder bh access members|listed|public [--tier viewer|editor] members = anyone in the workspace (at that tier); listed = only shared emails; public = anyone on the internet may read it (a website), writes still need sign-in bh secrets ls|set|rm NAME set reads the value from stdin or a prompt; restarts the tool bh users [add --role member|owner|guest] [invite ] [rm ] owners only bh billing balance, burn per day, days left, card, last ledger lines bh billing card optional page to replace or save a card for capped auto-refill bh billing topup 20 [--yes] quote, then secure Stripe checkout; the owner completes payment there bh billing autorefill 20 --cap 100 capped refill; omitted --cap allows at most one refill amount per month bh usage usage, hard limits, and any pause reason bh capacity --gb 2 quote a higher storage limit; requires owner approval bh capacity --yes --quote-id --max-monthly-cents bh prices the price sheet in words bh domain check availability and price bh domain buy [--yes --quote-id --max-cost-cents ] [--to ] quote first; confirm the same quote within the approved total; --to puts a tool on the domain's front bh domain ls | attach [--to ] | point --to | dns | repoint | primary | detach point = the domain itself and www. open that tool (a website on its own domain); tools also keep . bh domain free wire .boathousecloud.com (the free address) bh registrar status|connect|wait|keys host only: connect the registrar account (one approval click, nothing to copy) bh keys create --name [--for email] project keys for agents; shown once. Owners, members, and anyone who is admin on a tool can hold one bh rm [--purge --yes] without --purge the database, files, sharing and secrets stay and all come back when a tool of that name is deployed again; purge deletes them bh export [] [--dir .] [--all] one .tar.gz per tool: source/, database.sql, data/, README.txt (secrets left out) bh restore [--from YYYY-MM-DD] [--yes] database and files back from a nightly backup (03:35 UTC); plan first, --yes to do it; a copy of the current state is kept bh audit | bh whoami bh update re-download bh from the platform; bh skill refresh ~/.claude/skills/boathouse ``` ## How to ship a tool end to end 1. Build it with a Dockerfile listening on `$PORT`, tables created at startup from `DATABASE_URL`. 2. `bh deploy` in the folder. Read the URL back. If it fails, `bh releases ` shows the build or start log tail; fix and deploy again. 3. Secrets: `printf '%s' "$VALUE" | bh secrets set NAME -`. Never paste secret values into chat. 4. Sharing: new tools are visible to workspace members. `bh access listed` then `bh share` for anything sensitive. Pass on the invite link it prints. 5. Report the URL and who can see it. Do not open a browser; there is nothing to click. ## A website, not a tool A public site (a portfolio, a research database, a landing page) is `bh deploy` in the folder with the `index.html`, then `bh access public` so anyone can read it, then `bh domain buy example.com --yes --quote-id --max-cost-cents --to ` so it answers at example.com and www.example.com with HTTPS. Reads need no sign-in; anything that writes still does. ## How to give a workspace its own domain 1. `bh domain buy acme.example` returns the exact total and a quote ID. Confirm with `bh domain buy acme.example --yes --quote-id --max-cost-cents `. The prepaid workspace balance pays registrar cost plus Boathouse's margin. Reuse that quote ID after a timeout; the saved purchase identity prevents duplicate purchases or charges. A price over the approved limit is refused. 2. DNS is set by the same command (apex and wildcard A records). Certificates are issued on first visit. Allow a few minutes for DNS to spread. The first bought domain becomes the workspace's primary address. 3. A domain held elsewhere: `bh domain attach ` prints the two A records to make at that DNS host. ## Money, and the rule for spending it A workspace holds prepaid credit; nothing runs until money is on it (a deploy on an empty balance is refused with a 402 that says where the owner adds money). `bh referral` shows the person's referral code, link, QR image URL, and dashboard at https://boathousecloud.com/partners. Partners earn 10% of referred customers' paid hosting and storage usage for their lifetime, including future apps/workspaces on that customer account. Free credit, unused deposits, domains, taxes, refunds and disputes are excluded. Monthly cash payouts start at $10; smaller balances roll over. Customers receive half-price organization hosting for their first 60 days. Partners can join free without deploying an app. The dashboard tracks earnings and manual completed transfers; it does not send money. The organization costs exactly $10.00 for a full UTC calendar month for up to five tools, divided into daily charges while any tool runs; adding more tools within the allowance does not multiply that charge. Static sites and stopped tools count toward the five-tool limit. The first GB of storage in each tool is included, then $0.25/GB/month; a domain costs registrar price plus $2.00/year. At zero the workspace pauses (tools stop, nothing is deleted) and resumes on the next top-up. **Every command that spends money returns a quote first and does nothing else**: `bh domain buy x.example` and `bh billing topup 20` print the cost and stop; the agent shows the cost to the person, and only on their yes runs the same command with `--yes`. Never add `--yes` on your own. If the balance is short, do not try to charge the card yourself: tell the person the amount and point them at their workspace page (https://boathousecloud.com/account), where Add credit opens one secure Stripe checkout, including any bank verification. Card details never go through chat. Auto-refill is a separate, explicit approval with a monthly cap; then continue. ## New workspace from the terminal `bh signup "Acme Studio" owner@acme.example` creates a workspace and emails the owner a secure invitation. With `--code BH-XXXXXXXXXX`, it instead returns a signup link with the referral code filled in; the owner confirms their own email before the referral is attached. A referral makes every app half price for 60 days. After confirming their mailbox and choosing a password, the owner copies the connection from the welcome page. Agents that speak MCP connect to https://mcp.boathousecloud.com/mcp (Streamable HTTP) with header `Authorization: Bearer `: ``` claude mcp add --transport http boathouse https://mcp.boathousecloud.com/mcp --header "Authorization: Bearer bh_…" ``` The MCP tools are listed under "Getting connected" above; `deploy` takes a map of file paths to contents, and `domain_buy` first returns a `quote_id`; confirm with `confirm: true`, that same `quote_id`, and `max_cost_cents` within the user's approved budget. Keep the same quote ID on retries. A purchased domain with `dns_pending: true` needs `domain_repoint`, not another purchase. `topup` confirms with the `operation_id` from its preceding quote, the same `cents`, and `confirm: true`. Reuse operation IDs on retries; the CLI carries them automatically. ## Gotchas - `bh deploy` uploads everything in the folder except `.git`, `node_modules`, Python caches/environments, `.env`, `.env.*` (except example/sample/template files), and whatever `.dockerignore` lists; editor leftovers (`app.py.bak`, `notes.txt`) go up too and `bh pull` brings them back. Keep the folder clean or list them. - The slug comes from `boathouse.json` or the folder name; keep it stable or you create a second tool. - Every deploy replaces the container; anything not in `/data` or the database is gone. Files go under `DATA_DIR`. - `bh secrets set` restarts the tool. `bh secrets rm` takes effect on the next restart. - Rollback re-runs an earlier image with the current secrets; it does not touch the database. `bh restore` puts the database and files back from a nightly backup, and is a spending-style command: show the plan, act only on the person's yes (`--yes`). - `bh export` is the whole tool in one file (code, database as SQL, files) and runs anywhere with a Dockerfile; secrets are not in it. - Sessions are per domain: signing in on `acme.example` does not sign you in on the free address. - The registrar's own rules: one purchase attempt per 10 seconds, no premium names by API, prepaid balance only. ## Resource limits and growth On the managed service, an organization includes up to five lightweight tools for $10/month. All its app containers share 512 MB RAM and half a CPU core, enforced by one parent cgroup; these are not per-tool allowances. Each tool starts with 1 GB of combined database and file storage. A static website uses a tool slot. Lightweight means websites, forms, trackers, calculators and dashboards doing modest work in response to people. Large datasets, video processing, locally hosted AI models and continuously busy jobs need a reviewed plan. Calls to an external AI service may fit, but provider charges are separate. CPU work is throttled at the shared cap; memory exhaustion can kill/restart an app. Check `bh billing` for shared usage and `bh usage ` for storage; do not promise a fixed number of visitors. At most five tools can be created per organization, even when some are stopped. Deleted tools with retained data keep their storage allocation; request owner approval before purging it. Apps write persistent files to DATA_DIR; other app files are read-only and temporary directories are bounded. Builds run separately, one at a time, with 1 GB RAM, one CPU, 3 GB temporary storage and a five-minute deadline. Uploaded source expands to at most 256 MB; app images are at most 512 MB and source history at most 512 MB per app. Use `bh usage` before diagnosing a slow or paused app. Storage warnings appear in the account and are emailed to owners at 80% and 90%. An app near its storage limit pauses; its data remains. Native filesystem quotas enforce the hard limit even if the monitor is unavailable. PostgreSQL roles have 8 connections, bounded temporary query files and query timeouts. If capacity is unavailable on the host, a deployment is refused before replacing the current app. Never silently upgrade an app. Ask for a capacity quote, explain its maximum extra monthly cost, and confirm only the exact approved quote and price. Self-service storage is capped at 10 GB and depends on available host capacity. Larger workloads need operator review. CPU and memory increases also need operator review. Never tell someone a deployment is queued unless the service actually accepted it. ## Domain renewals Buying a domain also enables renewal from prepaid Boat House credit up to the quoted renewal limit. Show this ongoing renewal policy with the purchase quote. Boat House emails the price around 30 days before expiry, attempts renewal 14 days before expiry, and waits at least seven days after sending the price notice. A higher price requires owner approval; low credit or provider trouble stops the renewal and triggers a notice. Never fund the registrar account or charge a customer card on your own. Owners can manage this without a terminal at their account's **Manage domain renewals** link, including detached domains. For agents, `bh domain renewals` (MCP `domain_renewals`) reads expiry, status, limits and errors. `bh domain renewal --enabled on --max-cost-cents ` previews a change; add `--yes` only after approval. Use `--enabled off` to cancel future renewal, which lets the domain expire. MCP `domain_renewal_set` takes domain, enabled, max_cost_cents and confirm; preview before confirming. Detaching a domain does not turn renewal off. An in-flight renewal must finish reconciliation before its settings can change. --- Source: https://boathousecloud.com/docs/install-agent # How do I install Boat House in Cursor, Codex, Windsurf or Claude Code? Install the skill, then tell your agent what you want to publish. The skill teaches the agent to run Boat House's `bh` command. You sign in once and paste **Copy connection** from your account page; the agent handles the technical setup. Installation itself does not create an account, deploy an app or charge a card. ## Cursor, Codex and Windsurf Run this in your project, or ask your agent to run it: ```sh npx skills add allenzhangyiteng/boathouse-skills ``` Choose your agent in the installer. To select all three explicitly: ```sh npx skills add allenzhangyiteng/boathouse-skills --skill boathouse --agent cursor codex windsurf --yes ``` The current skills installer needs Node.js 22.20 or newer. The Boat House CLI needs Python 3.9 or newer. For all projects, add `--global`. Installing the skill gives the agent instructions; on first use it installs the CLI if needed. ## Claude Code Add our public marketplace once, then install its plugin inside Claude Code: ```text /plugin marketplace add allenzhangyiteng/boathouse-skills /plugin install boathouse@boathouse ``` This is Boat House's own marketplace. An official-directory submission is separate and is not an endorsement. The plugin includes the skill and an explicit `/boathouse:setup` command. It does not run a startup hook or silently change your credentials. When the plugin loads, say “Put this online with Boat House.” ## Runnable first example On macOS, Linux, or Windows with WSL, this installs the CLI without connecting an account, then creates a local starter: ```sh curl -fsSL https://boathousecloud.com/install.sh -o /tmp/boathouse-install.sh sh /tmp/boathouse-install.sh ~/.local/bin/boathouse init first-app --template team cd first-app python3 app.py --local ``` Open http://127.0.0.1:8080. Stop the preview with Ctrl+C. `boathouse` and `bh` refer to the same CLI. If another program already owns the `boathouse` filename, the installer preserves it; use `~/.local/bin/bh`. ## Connect when you are ready to publish Create your account, confirm your email, and use [Copy connection](/account). Paste the whole message into the agent conversation containing your app. The agent verifies `bh whoami`, checks your hosting balance and publishes only when requested. Keep connection codes private and let the browser handle passwords and card details. Hosting is $10 per organization per month for up to five lightweight tools, billed daily from prepaid credit. Domain purchases and approved extra storage are separate. [Create an app](/docs/create-app) or [deploy an existing app](/docs/deploy-claude-code-app). --- Source: https://boathousecloud.com/docs/create-app # How do I create an app that is ready for Boat House? Run `bh init`. It creates a complete project locally: app files, `boathouse.json`, instructions for your coding agent, and a README with preview and deployment commands. It needs no login, makes no network requests and refuses to overwrite existing files. ## Runnable team-app example After [installing the CLI](/docs/install-agent): ```sh bh init team-notebook --template team --name "Team notebook" cd team-notebook python3 app.py --local ``` Open http://127.0.0.1:8080 and add a note. Restart the preview: your note is still there. Local preview uses a synthetic admin and binds only to your computer. The sample data folder is excluded from deployment. Choose a fresh folder if `team-notebook` already exists. The team template uses Python's standard library. On Boat House it verifies the gateway's signed identity, checks the timestamp, gives viewers read-only access and lets editors add notes. Form tokens protect writes. Notes are stored in SQLite inside the persistent `DATA_DIR`. Everyone with access to this notebook can read the same notes; add record-level authorization if your application needs more private data within a team. ## A website instead ```sh bh init company-site --template static cd company-site python3 -m http.server 8080 --bind 127.0.0.1 ``` Edit `index.html`. [Publish the website](/docs/publish-static-website) when ready. ## The app format `boathouse.json` starts with `schemaVersion`, `slug` and `name`. The CLI adds deployment metadata such as `base` and `workspace` after publishing; keep those fields so stale updates and workspace mistakes are caught. The slug selects the app, so changing it creates a different deployment target. A static app has an `index.html` at the project root. A server app has a `Dockerfile`, listens on `0.0.0.0:$PORT` (8080 by default), and writes persistent files only under `DATA_DIR`. Boat House provides `DATABASE_URL` for PostgreSQL and signed identity headers plus `BOATHOUSE_SIGNING_KEY` for authorization. Keep secrets in environment variables, never in client code or source archives. There is no proprietary runtime dependency. You own ordinary Python/HTML/Docker source and can export your app and data. The templates are Apache 2.0 licensed. ## Publish after preview Stop the local server, connect your account and add hosting credit. From the app folder: ```sh bh whoami bh deploy ``` New apps are private by default. [Share access](/docs/share-with-team), then verify with a second account before using real business data. Read the [security limitations](/security) first. --- Source: https://boathousecloud.com/docs/deploy-claude-code-app # How do I deploy a Claude Code app with team login? Connect Claude Code to Boat House once, then say “Put this app online and keep it private to my team.” Your agent prepares the files, runs the deployment and returns a stable HTTPS link. Codex, Cursor and Windsurf can use the same CLI and app format. You do not need separate hosting, database and sign-in projects. Boat House supplies those pieces. Your app still needs to implement its own data permissions and any connections to outside services. ## Runnable example After [installing Boat House](/docs/install-agent), start with a complete working app: ```sh bh init launch-demo --template team cd launch-demo python3 app.py --local ``` Open http://127.0.0.1:8080, add a note, then stop the preview with Ctrl+C. This runs without an account or payment. To publish, sign up at Boat House, confirm your email and paste **Copy connection** from [your account](/account) into Claude Code. Add hosting credit in the browser. Then the agent runs from the project folder: ```sh bh whoami bh deploy bh status launch-demo ``` Use the URL printed by `bh deploy`; it contains your actual organization address. Open it while signed out to check that login is required, then sign in. Add a note and reload. The local preview's synthetic notes were not uploaded; the hosted app starts with its own persistent data. ## Deploy the app you already built The agent checks for an `index.html` or a `Dockerfile` and adapts the project if necessary. A server must listen on the supplied `PORT`, store files in `DATA_DIR`, and use `DATABASE_URL` when it needs the managed PostgreSQL database. Native serverless/edge functions may need adaptation; an existing database needs a planned data migration. Existing source is not overwritten by `bh init`. Ask the agent to check logs and exercise the real workflow after deployment. Publishing a working container does not prove every feature or permission works. ## Share and update Tell your agent the teammate's email and whether they should view, edit data or administer the app. [Sharing instructions](/docs/share-with-team) explain those roles. To publish later changes, run `bh deploy` again from the same folder; Boat House keeps releases and rejects stale source updates. Managed hosting costs $10 per organization per month for up to five lightweight tools. Connecting an agent can take about 90 seconds after email confirmation; payment, dependency installation and builds take additional time. Domain purchases and approved storage increases are separate. --- Source: https://boathousecloud.com/docs/share-with-team # How do I share my app and its data with my team? Tell your connected agent who should have access and what they should be able to do. For example: “Share the notebook with my co-founder as an editor.” If the agent cannot infer the email, it asks for that one missing detail. Teammates use their own login and the same live app and data. Viewers read. Editors use the app's editing features. Admins can change source code, secrets, sharing and deployments, including deleting the app. Admin is appropriate for trusted developers, not everyone who edits a spreadsheet-like record. There is no Boat House per-person hosting seat charge. ## Runnable example Create and preview a notebook first: ```sh bh init shared-notebook --template team cd shared-notebook python3 app.py --local ``` Open http://127.0.0.1:8080. Stop with Ctrl+C. After connecting and funding your Boat House account, publish: ```sh bh whoami bh deploy ``` Set `TEAMMATE_EMAIL` to the real email you intend to invite, then run: ```sh bh share shared-notebook "${TEAMMATE_EMAIL:?Set the email of the person you intend to invite}" --tier editor ``` That last command grants access and sends an invitation. Do not use an invented or sample address. The owner can instead ask the agent to run the command with a confirmed email. ## Confirm it works The invited person opens their email, verifies the invitation and signs in. They should see the same notes and be able to add one. Give a different test account Viewer access and confirm that it cannot add notes. Removing access with `bh unshare` must prevent subsequent access. The app must enforce record-level restrictions if some notes should be hidden from some team members. ## Let another developer use their agent Grant Admin only when the person should control the software itself. They connect their own agent, then run `bh pull organization/shared-notebook`, edit the downloaded project and run `bh deploy`. They use the same hosted app and release history. They do not need to receive your API key or password, and they can use a different supported coding agent. This is source checkout and versioned publishing, not simultaneous character-by-character code editing. Boat House detects stale updates so one developer does not silently replace another's newer release. --- Source: https://boathousecloud.com/docs/publish-static-website # How do I put a static website online with Boat House? Boat House can host an ordinary HTML/CSS/JavaScript website. Your agent publishes the files and gets an HTTPS URL. A static site counts as one of the five lightweight tools in the organization plan. ## Runnable example After [installing the CLI](/docs/install-agent): ```sh bh init company-site --template static cd company-site python3 -m http.server 8080 --bind 127.0.0.1 ``` Open http://127.0.0.1:8080 and edit `index.html`. Stop with Ctrl+C, connect your account and add hosting credit, then publish: ```sh bh whoami bh deploy ``` Open the deployment URL. New deployments start private. If this is intended to be a public website, explicitly make it readable by anyone: ```sh bh access company-site public ``` Check the URL in a signed-out browser. It should now open without login. To restrict it to organization members again: ```sh bh access company-site members ``` ## What a static site can and cannot do The browser can download the published HTML, JavaScript and other deployed files. Never include credentials or confidential data. Static files cannot safely hold secret API keys, process private writes or independently verify a user for a backend. Use a server app for those features. If a frontend framework produces a build folder, have the agent run its build and deploy the output folder containing `index.html`. Server rendering and API routes require a compatible server container; they are not ordinary static files. ## Update or use your own domain Edit the project and run `bh deploy` again. [Connect a domain](/docs/connect-domain) if you want your own business address. Domain registration is separate from hosting and requires an approved price. --- Source: https://boathousecloud.com/docs/add-team-login # How do I add team login to an existing app? Deploy the app to Boat House and keep its access private. The Boat House gateway handles sign-in and passes signed identity headers to the app. Your backend verifies those headers and enforces what each person can read or change. A login page alone is not application security. Preserve your app's existing permissions until the replacement has been tested. Publishing an app must not silently make it public or remove its authorization checks. ## Runnable reference The team starter includes working identity verification and a read/write example: ```sh bh init login-reference --template team cd login-reference python3 app.py --local ``` Open http://127.0.0.1:8080. The local-only synthetic login lets you inspect the notebook without an account. In `app.py`, read `identity`, `valid_csrf`, `do_GET` and `do_POST` before adapting the pattern to your existing backend. Stop the preview with Ctrl+C. After connecting your account and adding credit, test the hosted version: ```sh bh whoami bh deploy bh access login-reference listed ``` Only explicitly granted people can access it. Open the returned URL signed out and verify the login redirect. Test separate Viewer and Editor accounts before replacing your existing authentication. ## The signed identity contract Boat House provides `X-Boathouse-User`, `X-Boathouse-Tier`, `X-Boathouse-Labels`, `X-Boathouse-Ts` and `X-Boathouse-Sig`. Recompute HMAC-SHA256 over `user|tier|labels|BOATHOUSE_TOOL|timestamp` using the server-only `BOATHOUSE_SIGNING_KEY`. Compare in constant time and reject missing, invalid or stale signatures. The starter accepts a maximum five-minute clock difference. Only the signed fields should drive authorization. Do not trust an arbitrary browser header or an unsigned display name. Never expose the signing key in client JavaScript, logs or source. The gateway blocks non-read requests from Viewers as an additional safeguard. The backend must still protect write routes, validate form tokens and enforce record-level permissions. Avoid state-changing GET requests. Public apps can receive an empty user with Viewer access; requiring a named user remains an application decision. ## Existing accounts and data An existing login/database integration may require mapping accounts and moving data. Plan and verify that migration separately. Boat House cannot guarantee that an arbitrary generated app is secure; review [current security controls and limitations](/security). --- Source: https://boathousecloud.com/docs/connect-domain # How do I give my app a real domain name? Every Boat House app already has an HTTPS address. A custom domain is optional. Your agent can connect a domain you own, or check availability and show a purchase quote. It should establish which domain you mean and what you approve before spending money or changing live DNS. ## Runnable example without buying anything Create a small website locally: ```sh bh init domain-demo --template static cd domain-demo python3 -m http.server 8080 --bind 127.0.0.1 ``` Open http://127.0.0.1:8080, then stop with Ctrl+C. After connecting your account, these commands inspect your account and existing domains without purchasing or changing DNS: ```sh bh whoami bh domain ls bh domain renewals ``` Set `DOMAIN` to the domain you want to check, then: ```sh bh domain check "${DOMAIN:?Set the exact domain to check}" ``` Checking does not reserve or purchase a domain. Publish with `bh deploy` after adding hosting credit; keep the free URL while reviewing the custom-domain plan. ## If you already own the domain Tell the agent where it is registered and which app should answer there. The agent checks existing DNS before applying changes. For a registrar-managed domain connected to Boat House, `bh domain attach DOMAIN --to APP_SLUG` attaches it and points the app. Other registrars can require access to their DNS settings. Do not overwrite unrelated email records or another production website. ## If you want to buy a domain Ask for the exact domain. `bh domain buy DOMAIN` first obtains a quote; it does not purchase without confirmation. The agent should state the total, registration duration and renewal price, then use the same quote ID and your maximum approved cost when confirming. Retry an uncertain purchase with that same operation; do not create a fresh order. Domain purchases use prepaid Boat House credit. Boat House pays the registrar from its own registrar balance. The quoted price includes the registrar cost plus Boat House's $2-per-year fee; it is separate from the organization hosting plan. Availability and registrar credit can change before confirmation. ## Renewals The owner controls auto-renewal and the maximum annual price on the account's Domains page or through `bh domain renewal`. Boat House sends advance notices and uses prepaid credit only within the approved limit. Insufficient customer or registrar credit can prevent renewal. Detaching a domain from an app does not cancel its renewal policy; review that setting separately.