@cabane/cli 0.1.4 → 0.1.5

package/README.md

@@ -1,27 +1,24 @@
 # cabane CLI
 
 Run a self-hosted [Cabane](https://cabane.ai) on your own machine. `@cabane/cli`
-installs the Cabane server, runs the whole stack — server, embedded Postgres,
-and the house bridge — and keeps it updated.
+installs the Cabane server, runs the whole stack — server plus embedded Postgres —
+and keeps it updated.
 
-Two terms you'll see throughout:
-
-- The **house bridge** is what makes your agents answer: it runs each agent
-  turn on your machine, through an executor.
-- An **executor** is a coding-agent harness installed on your machine —
-  **Claude Code**, **Codex**, or **opencode**. Cabane ships no model of its own
-  and requires no particular provider; the house bridge runs whichever executor
-  (and credentials) you have.
+That's the whole server side — your workspace, its files, and its data. **Agents
+run the same way they do on hosted Cabane: on a [companion](https://app.cabane.ai/docs/reference/companion)
+you pair**, on a device you control, using the harness (Claude Code, Codex, or
+OpenCode) and credential already there. The self-hosted server runs no agent turns
+itself and needs no model key of its own.
 
 The short version:
 
 ```sh
 npm i -g @cabane/cli                 # install the CLI (bin: `cabane`)
-cabane init                          # first-run wizard
+cabane init                          # first-run wizard (data location, port, URL)
 cabane install --token cabdist_…     # fetch + verify + unpack the server
 cabane up --daemon                   # run the stack
 # open http://localhost:3000, sign up
-cabane setup-agent                   # connect your agent to the house bridge
+cabane setup-agent                   # confirm your account + how to pair a companion
 ```
 
 Each step, in order, below.
@@ -29,8 +26,10 @@ Each step, in order, below.
 ## Requirements
 
 - **Node ≥ 22.**
-- **An executor the house bridge can run** — Claude Code, Codex, or opencode —
-  with its credentials reachable (see [Credentials](#credentials)).
+- **A companion to run your agents** — the desktop Companion or the headless
+  `@cabane/companion`, on a device you control, with a coding-agent harness (Claude
+  Code, Codex, or OpenCode) installed and signed in. The server itself needs no
+  model credential.
 
 ## Getting started
 
@@ -38,35 +37,34 @@ Each step, in order, below.
 
 2. **Run `cabane init`** — the interactive first-run wizard. It asks where your
    data lives (and shows the resolved paths — `data/storage` for uploads,
-   `data/pg` for the database), the port, an optional public URL, and your
-   executor credential if you use API-key billing (on a Claude subscription
-   login there's nothing to enter — see [Credentials](#credentials)). Everything
-   persists to config, so a later `cabane up` needs no flags. Re-run it any time
-   to reconfigure, or skip it and pass flags directly if you prefer.
+   `data/pg` for the database), the port, and an optional public URL. Everything
+   persists to config, so a later `cabane up` needs no flags. Re-run it any time to
+   reconfigure, or skip it and pass flags directly if you prefer.
 
 3. **Run `cabane install --token cabdist_…`** — fetches the server artifact with
    your distribution token, verifies its sha256, and unpacks it. (Have a local
    tarball instead? `cabane install --from <artifact.tgz>` works offline.)
 
 4. **Run `cabane up --daemon`** — starts and supervises the stack: embedded
-   Postgres, the server, and the house bridge. Leave off `--daemon` to run it in
-   the foreground.
+   Postgres and the server. Leave off `--daemon` to run it in the foreground.
 
 5. **Sign up.** Open <http://localhost:3000> and create your account and first
    workspace.
 
-6. **Run `cabane setup-agent`** — the step that connects your agent to your
-   executor. Mint an access token in the app (**Settings → Developer**), then
-   run `cabane setup-agent` and paste the `cab_…` token at the prompt. That
-   registers the house bridge and puts your agent on it — your agent now
-   answers in chat.
+6. **Pair a companion.** Your workspace seeds an agent, but it has nowhere to run
+   until you pair a device. `cabane setup-agent` (mint an access token in
+   **Settings → Developer**, paste it at the prompt) confirms your account and
+   prints the steps: install the Companion (desktop app, or the headless
+   `@cabane/companion`), sign in against this instance, pair it, then assign the
+   seeded agent to one of its connectors. This is the same pairing flow as hosted
+   Cabane.
 
-For the fuller picture of what you just stood up — agents, bridges, workspaces,
-files — see the [Cabane docs](https://app.cabane.ai/docs).
+For the fuller picture of what you just stood up — agents, workspaces, files —
+see the [Cabane docs](https://app.cabane.ai/docs).
 
 ## What it supervises
 
-`cabane up` runs three children in order, with a clean SIGTERM teardown:
+`cabane up` runs two children in order, with a clean SIGTERM teardown:
 
 1. **Embedded Postgres** — the `embedded-postgres` binaries (pinned pg 16.14) run
    as a child on a local off-5432 port; data in `<CABANE_HOME>/data/pg`. No system
@@ -74,30 +72,29 @@ files — see the [Cabane docs](https://app.cabane.ai/docs).
 2. **The server** — the artifact's single-process API+SPA (`server.js`, filesystem
    storage, the bundled SPA served via `WEB_DIST`), env composed automatically
    (`NODE_ENV=production`, `http://localhost:<port>`, generated-once vision
-   secret). Migrations apply on boot.
-3. **The house bridge** — bundled inside the server artifact from the same commit
-   (`<appDir>/bridge`), run as the house executor so your agents answer, always in
-   version lockstep with the server. Configured by `cabane setup-agent`.
+   secret, any persisted `cabane set-env` creds). Migrations apply on boot.
+
+Agents don't run here — they run on a companion you pair (a separate process on a
+device you control), the same as hosted Cabane.
 
 ## Layout (`~/.cabane-selfhost/`)
 
 ```
-config.json          the CLI's config (token, port, versions, house ids)
+config.json          the CLI's config (token, port, versions, persisted creds)
 app/<version>/       each installed artifact tree
 data/pg/             Postgres data dir
 data/storage/        file bytes (filesystem storage backend)
-bridge/              the house bridge's isolated HOME
-logs/                server.log · bridge.log
+logs/                server.log
 run/                 supervisor.pid · state.json
 ```
 
 The root defaults to **`~/.cabane-selfhost/`** — deliberately _not_ `~/.cabane`,
-which a standalone `@cabane/bridge` user bridge already keys off, so a self-host
-install can never clobber a bridge's device pairing on a shared box. Override the
-whole root with the **`CABANE_HOME`** env var (the multi-instance lever); a
-pre-existing self-host install still living at `~/.cabane` is adopted in place, so
-no data moves. A `cabane install` / `set-env` pointed (via `CABANE_HOME`) at a
-directory that holds a bridge config refuses rather than overwrite it.
+which a standalone `@cabane/companion` user companion already keys off, so a
+self-host install can never clobber a companion's device pairing on a shared box.
+Override the whole root with the **`CABANE_HOME`** env var (the multi-instance
+lever); a pre-existing self-host install still living at `~/.cabane` is adopted in
+place, so no data moves. A `cabane install` / `set-env` pointed (via `CABANE_HOME`)
+at a directory that holds a companion config refuses rather than overwrite it.
 
 **Relocating just the data.** `cabane init` can point the **data** leg (pg +
 storage) at any path you choose while `config.json` + `app/` stay under the root —
@@ -115,17 +112,28 @@ paths so you can see it.
 
 | Command              | What it does                                                                                  |
 | -------------------- | --------------------------------------------------------------------------------------------- |
-| `cabane init`        | interactive first-run wizard: data location, port, public URL, executor credential            |
+| `cabane init`        | interactive first-run wizard: data location, port, public URL                                 |
 | `cabane install`     | fetch (token → gated artifact) or `--from` a local tarball; unpack + `npm install --omit=dev` |
 | `cabane up`          | start + supervise the stack (`--daemon` for background)                                       |
-| `cabane setup-agent` | after signup: register the house bridge, assign your agent                                    |
+| `cabane setup-agent` | after signup: confirm your account + print companion-pairing guidance                         |
 | `cabane update`      | install a newer published artifact (keeps N-1 for rollback)                                   |
-| `cabane set-env`     | persist `KEY=VALUE` credentials forwarded to the house bridge (`--list` / `--unset`)          |
+| `cabane set-env`     | persist generic `KEY=VALUE` server env forwarded to the server (`--list` / `--unset`)         |
 | `cabane down`        | stop a running stack                                                                          |
 | `cabane status`      | what's installed + running                                                                    |
-| `cabane logs`        | tail the server + bridge logs                                                                 |
+| `cabane logs`        | tail the server log                                                                           |
 | `cabane doctor`      | preflight: diagnose common self-host failure classes (runs with the stack down)               |
 
+## Running agents
+
+A self-hosted server runs no agent turns itself. Agents run exactly as on hosted
+Cabane: on a companion you pair against your instance. Install the desktop
+Companion or the headless `@cabane/companion` on a device you control, sign in
+against your self-hosted URL, pair it, and assign your agents to its connectors.
+The turn runs in the harness on that device — Claude Code, Codex, or OpenCode —
+against the login or key already there; the server never sees the credential. For a
+single-box setup, the companion can run on the same machine as the server (point it
+at `http://localhost:3000`).
+
 ## Troubleshooting — `cabane doctor`
 
 When something won't start, run `cabane doctor` **first**. It's a standalone
@@ -135,53 +143,32 @@ pass/fail/warn report, each with a one-line fix, then exits non-zero if any hard
 check fails. It's strictly local — nothing phones home. Checks:
 
 - **Node** ≥ the required version.
-- **Executor** — your executor's binary on PATH (`claude` by default), and a
-  credential reachable by the house bridge (a subscription login, or an
-  `ANTHROPIC_*` env/persisted key). Reachability only; it never calls the
-  provider.
 - **Port** free (or held by a running cabane).
 - **Embedded Postgres** — platform binaries present + data dir healthy.
 - **Storage root** — writable, and where it is.
-- **Bridge/server version** — the bridge bundled in the installed artifact
-  matches the server it ships with (a version skew from a mismatched install is
-  flagged).
 - **Disk space** for the data dir.
 - **macOS Gatekeeper** — quarantine on the Postgres binaries (macOS only).
 
-## Credentials
-
-The house bridge inherits the environment `cabane up` runs under, so your
-executor's credentials reach it — no provider is special-cased:
-
-- **Claude subscription** — a logged-in Claude Code just works; its OAuth creds
-  live on disk under `~/.claude` (pointed at by `CLAUDE_CONFIG_DIR`), so there's
-  nothing to export.
-- **API-key billing (or any executor keyed by an env var)** — the key lives in
-  your environment, not on disk, so make it reachable one of two ways:
-
-  ```sh
-  # the wizard — `cabane init` prompts for it password-style and persists it
-  cabane init
-
-  # persisted, on its own — save once; every future `up` (fresh shell, reboot) picks it up.
-  # A bare KEY prompts for the value (hidden); `KEY=VALUE` still works for scripting.
-  cabane set-env ANTHROPIC_API_KEY
-  cabane up --daemon
-
-  # ambient — export in the shell you launch from
-  export ANTHROPIC_API_KEY=sk-ant-…
-  cabane up --daemon
-  ```
-
-`set-env` stores generic `KEY=VALUE` pairs in `<CABANE_HOME>/config.json` and composes
-them into the bridge on every `up`, so it serves any executor's credentials (a
-proxy `ANTHROPIC_BASE_URL`, an `ANTHROPIC_AUTH_TOKEN`, another harness's key) —
-not just Anthropic. A bare `cabane set-env KEY` (no `=value`) prompts for the value
-without echoing, so a secret never lands on the command line. Inspect with `cabane
-set-env --list` (values masked), remove with `cabane set-env --unset KEY`. A live shell export takes precedence over a
-persisted value; the house-class isolation vars (`HOME`, `CLAUDE_CONFIG_DIR`,
-class) always win over both. Apply a change to an already-running stack with
-`cabane down && cabane up`.
+## Server env — `cabane set-env`
+
+The self-hosted server needs no model credential of its own. `cabane set-env` stays
+for any generic server env you _do_ want to persist:
+
+```sh
+# persisted — save once; every future `up` (fresh shell, reboot) picks it up.
+# A bare KEY prompts for the value (hidden); `KEY=VALUE` still works for scripting.
+cabane set-env SOME_KEY
+cabane down && cabane up --daemon
+```
+
+It stores generic `KEY=VALUE` pairs in `<CABANE_HOME>/config.json` and layers them
+into the server's env on every `up` — beneath the composed infra vars, so an
+operator key reaches the server but can never clobber `DATABASE_URL` / `NODE_ENV` /
+`STORAGE_*`. A bare `cabane set-env KEY` (no `=value`) prompts for the value without
+echoing, so a secret never lands on the command line. Inspect with
+`cabane set-env --list` (values masked), remove with `cabane set-env --unset KEY`.
+A live shell export takes precedence over a persisted value. Apply a change to an
+already-running stack with `cabane down && cabane up`.
 
 ## Notes