@cabane/cli 0.1.3 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +104 -92
- package/dist/cli.js +284 -730
- package/package.json +4 -5
package/README.md
CHANGED
|
@@ -1,38 +1,70 @@
|
|
|
1
1
|
# cabane CLI
|
|
2
2
|
|
|
3
|
-
Run a self-hosted Cabane on your own machine
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Run a self-hosted [Cabane](https://cabane.ai) on your own machine. `@cabane/cli`
|
|
4
|
+
installs the Cabane server, runs the whole stack — server plus embedded Postgres —
|
|
5
|
+
and keeps it updated.
|
|
6
|
+
|
|
7
|
+
That's the whole server side — your workspace, its files, and its data. **Agents
|
|
8
|
+
run the same way they do on hosted Cabane: on a [companion](https://app.cabane.ai/docs/reference/companion)
|
|
9
|
+
you pair**, on a device you control, using the harness (Claude Code, Codex, or
|
|
10
|
+
OpenCode) and credential already there. The self-hosted server runs no agent turns
|
|
11
|
+
itself and needs no model key of its own.
|
|
12
|
+
|
|
13
|
+
The short version:
|
|
6
14
|
|
|
7
15
|
```sh
|
|
8
16
|
npm i -g @cabane/cli # install the CLI (bin: `cabane`)
|
|
9
|
-
cabane init # first-run wizard
|
|
10
|
-
cabane install --token cabdist_… # fetch +
|
|
11
|
-
cabane up --daemon #
|
|
17
|
+
cabane init # first-run wizard (data location, port, URL)
|
|
18
|
+
cabane install --token cabdist_… # fetch + verify + unpack the server
|
|
19
|
+
cabane up --daemon # run the stack
|
|
12
20
|
# open http://localhost:3000, sign up
|
|
13
|
-
cabane setup-agent #
|
|
21
|
+
cabane setup-agent # confirm your account + how to pair a companion
|
|
14
22
|
```
|
|
15
23
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
24
|
+
Each step, in order, below.
|
|
25
|
+
|
|
26
|
+
## Requirements
|
|
27
|
+
|
|
28
|
+
- **Node ≥ 22.**
|
|
29
|
+
- **A companion to run your agents** — the desktop Companion or the headless
|
|
30
|
+
`@cabane/companion`, on a device you control, with a coding-agent harness (Claude
|
|
31
|
+
Code, Codex, or OpenCode) installed and signed in. The server itself needs no
|
|
32
|
+
model credential.
|
|
33
|
+
|
|
34
|
+
## Getting started
|
|
35
|
+
|
|
36
|
+
1. **Install the CLI.** `npm i -g @cabane/cli` — installs the `cabane` binary.
|
|
37
|
+
|
|
38
|
+
2. **Run `cabane init`** — the interactive first-run wizard. It asks where your
|
|
39
|
+
data lives (and shows the resolved paths — `data/storage` for uploads,
|
|
40
|
+
`data/pg` for the database), the port, and an optional public URL. Everything
|
|
41
|
+
persists to config, so a later `cabane up` needs no flags. Re-run it any time to
|
|
42
|
+
reconfigure, or skip it and pass flags directly if you prefer.
|
|
43
|
+
|
|
44
|
+
3. **Run `cabane install --token cabdist_…`** — fetches the server artifact with
|
|
45
|
+
your distribution token, verifies its sha256, and unpacks it. (Have a local
|
|
46
|
+
tarball instead? `cabane install --from <artifact.tgz>` works offline.)
|
|
47
|
+
|
|
48
|
+
4. **Run `cabane up --daemon`** — starts and supervises the stack: embedded
|
|
49
|
+
Postgres and the server. Leave off `--daemon` to run it in the foreground.
|
|
22
50
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
/ `cabane set-env KEY`), and the `cab_…` access token (`cabane setup-agent`) — so
|
|
26
|
-
none of them land in your shell history or on screen.
|
|
51
|
+
5. **Sign up.** Open <http://localhost:3000> and create your account and first
|
|
52
|
+
workspace.
|
|
27
53
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
54
|
+
6. **Pair a companion.** Your workspace seeds an agent, but it has nowhere to run
|
|
55
|
+
until you pair a device. `cabane setup-agent` (mint an access token in
|
|
56
|
+
**Settings → Developer**, paste it at the prompt) confirms your account and
|
|
57
|
+
prints the steps: install the Companion (desktop app, or the headless
|
|
58
|
+
`@cabane/companion`), sign in against this instance, pair it, then assign the
|
|
59
|
+
seeded agent to one of its connectors. This is the same pairing flow as hosted
|
|
60
|
+
Cabane.
|
|
61
|
+
|
|
62
|
+
For the fuller picture of what you just stood up — agents, workspaces, files —
|
|
63
|
+
see the [Cabane docs](https://app.cabane.ai/docs).
|
|
32
64
|
|
|
33
65
|
## What it supervises
|
|
34
66
|
|
|
35
|
-
`cabane up` runs
|
|
67
|
+
`cabane up` runs two children in order, with a clean SIGTERM teardown:
|
|
36
68
|
|
|
37
69
|
1. **Embedded Postgres** — the `embedded-postgres` binaries (pinned pg 16.14) run
|
|
38
70
|
as a child on a local off-5432 port; data in `<CABANE_HOME>/data/pg`. No system
|
|
@@ -40,30 +72,29 @@ export or persist your key.
|
|
|
40
72
|
2. **The server** — the artifact's single-process API+SPA (`server.js`, filesystem
|
|
41
73
|
storage, the bundled SPA served via `WEB_DIST`), env composed automatically
|
|
42
74
|
(`NODE_ENV=production`, `http://localhost:<port>`, generated-once vision
|
|
43
|
-
secret). Migrations apply on boot.
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
75
|
+
secret, any persisted `cabane set-env` creds). Migrations apply on boot.
|
|
76
|
+
|
|
77
|
+
Agents don't run here — they run on a companion you pair (a separate process on a
|
|
78
|
+
device you control), the same as hosted Cabane.
|
|
47
79
|
|
|
48
80
|
## Layout (`~/.cabane-selfhost/`)
|
|
49
81
|
|
|
50
82
|
```
|
|
51
|
-
config.json the CLI's config (token, port, versions,
|
|
83
|
+
config.json the CLI's config (token, port, versions, persisted creds)
|
|
52
84
|
app/<version>/ each installed artifact tree
|
|
53
85
|
data/pg/ Postgres data dir
|
|
54
86
|
data/storage/ file bytes (filesystem storage backend)
|
|
55
|
-
|
|
56
|
-
logs/ server.log · bridge.log
|
|
87
|
+
logs/ server.log
|
|
57
88
|
run/ supervisor.pid · state.json
|
|
58
89
|
```
|
|
59
90
|
|
|
60
91
|
The root defaults to **`~/.cabane-selfhost/`** — deliberately _not_ `~/.cabane`,
|
|
61
|
-
which a standalone `@cabane/
|
|
62
|
-
install can never clobber a
|
|
63
|
-
whole root with the **`CABANE_HOME`** env var (the multi-instance
|
|
64
|
-
pre-existing self-host install still living at `~/.cabane` is adopted in
|
|
65
|
-
no data moves. A `cabane install` / `set-env` pointed (via `CABANE_HOME`)
|
|
66
|
-
directory that holds a
|
|
92
|
+
which a standalone `@cabane/companion` user companion already keys off, so a
|
|
93
|
+
self-host install can never clobber a companion's device pairing on a shared box.
|
|
94
|
+
Override the whole root with the **`CABANE_HOME`** env var (the multi-instance
|
|
95
|
+
lever); a pre-existing self-host install still living at `~/.cabane` is adopted in
|
|
96
|
+
place, so no data moves. A `cabane install` / `set-env` pointed (via `CABANE_HOME`)
|
|
97
|
+
at a directory that holds a companion config refuses rather than overwrite it.
|
|
67
98
|
|
|
68
99
|
**Relocating just the data.** `cabane init` can point the **data** leg (pg +
|
|
69
100
|
storage) at any path you choose while `config.json` + `app/` stay under the root —
|
|
@@ -81,85 +112,66 @@ paths so you can see it.
|
|
|
81
112
|
|
|
82
113
|
| Command | What it does |
|
|
83
114
|
| -------------------- | --------------------------------------------------------------------------------------------- |
|
|
84
|
-
| `cabane init` | interactive first-run wizard: data location, port, public URL
|
|
115
|
+
| `cabane init` | interactive first-run wizard: data location, port, public URL |
|
|
85
116
|
| `cabane install` | fetch (token → gated artifact) or `--from` a local tarball; unpack + `npm install --omit=dev` |
|
|
86
117
|
| `cabane up` | start + supervise the stack (`--daemon` for background) |
|
|
87
|
-
| `cabane setup-agent` | after signup:
|
|
118
|
+
| `cabane setup-agent` | after signup: confirm your account + print companion-pairing guidance |
|
|
88
119
|
| `cabane update` | install a newer published artifact (keeps N-1 for rollback) |
|
|
89
|
-
| `cabane set-env` | persist `KEY=VALUE`
|
|
120
|
+
| `cabane set-env` | persist generic `KEY=VALUE` server env forwarded to the server (`--list` / `--unset`) |
|
|
90
121
|
| `cabane down` | stop a running stack |
|
|
91
122
|
| `cabane status` | what's installed + running |
|
|
92
|
-
| `cabane logs` | tail the server
|
|
123
|
+
| `cabane logs` | tail the server log |
|
|
93
124
|
| `cabane doctor` | preflight: diagnose common self-host failure classes (runs with the stack down) |
|
|
94
125
|
|
|
126
|
+
## Running agents
|
|
127
|
+
|
|
128
|
+
A self-hosted server runs no agent turns itself. Agents run exactly as on hosted
|
|
129
|
+
Cabane: on a companion you pair against your instance. Install the desktop
|
|
130
|
+
Companion or the headless `@cabane/companion` on a device you control, sign in
|
|
131
|
+
against your self-hosted URL, pair it, and assign your agents to its connectors.
|
|
132
|
+
The turn runs in the harness on that device — Claude Code, Codex, or OpenCode —
|
|
133
|
+
against the login or key already there; the server never sees the credential. For a
|
|
134
|
+
single-box setup, the companion can run on the same machine as the server (point it
|
|
135
|
+
at `http://localhost:3000`).
|
|
136
|
+
|
|
95
137
|
## Troubleshooting — `cabane doctor`
|
|
96
138
|
|
|
97
139
|
When something won't start, run `cabane doctor` **first**. It's a standalone
|
|
98
140
|
preflight (no server needed — it's what you reach for precisely when things are
|
|
99
141
|
broken) that checks the common self-host failure classes and prints a legible
|
|
100
142
|
pass/fail/warn report, each with a one-line fix, then exits non-zero if any hard
|
|
101
|
-
check fails. It's strictly local — nothing phones home.
|
|
143
|
+
check fails. It's strictly local — nothing phones home. Checks:
|
|
102
144
|
|
|
103
145
|
- **Node** ≥ the required version.
|
|
104
|
-
- **Executor** — Claude Code present on PATH, and a credential reachable by the
|
|
105
|
-
house bridge (subscription login, an `ANTHROPIC_*` env/persisted key, or a
|
|
106
|
-
managed-policy that would refuse your key — named specifically). Reachability
|
|
107
|
-
only; it never calls the provider.
|
|
108
146
|
- **Port** free (or held by a running cabane).
|
|
109
147
|
- **Embedded Postgres** — platform binaries present + data dir healthy.
|
|
110
148
|
- **Storage root** — writable, and where it is.
|
|
111
|
-
- **Bridge/server version** — the bridge bundled in the installed artifact
|
|
112
|
-
matches the server it ships with (a version skew from a mismatched install is
|
|
113
|
-
flagged).
|
|
114
149
|
- **Disk space** for the data dir.
|
|
115
150
|
- **macOS Gatekeeper** — quarantine on the Postgres binaries (macOS only).
|
|
116
151
|
|
|
117
|
-
##
|
|
152
|
+
## Server env — `cabane set-env`
|
|
118
153
|
|
|
119
|
-
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
# the wizard — `cabane init` prompts for it password-style and persists it
|
|
138
|
-
cabane init
|
|
139
|
-
|
|
140
|
-
# persisted, on its own — save once; every future `up` (fresh shell, reboot) picks it up.
|
|
141
|
-
# A bare KEY prompts for the value (hidden); `KEY=VALUE` still works for scripting.
|
|
142
|
-
cabane set-env ANTHROPIC_API_KEY
|
|
143
|
-
cabane up --daemon
|
|
144
|
-
|
|
145
|
-
# ambient — export in the shell you launch from
|
|
146
|
-
export ANTHROPIC_API_KEY=sk-ant-…
|
|
147
|
-
cabane up --daemon
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
`set-env` stores generic `KEY=VALUE` pairs in `<CABANE_HOME>/config.json` and composes
|
|
151
|
-
them into the bridge on every `up`, so it serves any executor's credentials (a
|
|
152
|
-
proxy `ANTHROPIC_BASE_URL`, an `ANTHROPIC_AUTH_TOKEN`, a future harness's key) —
|
|
153
|
-
not just Anthropic. A bare `cabane set-env KEY` (no `=value`) prompts for the value
|
|
154
|
-
without echoing, so a secret never lands on the command line. Inspect with `cabane
|
|
155
|
-
set-env --list` (values masked), remove with `cabane set-env --unset KEY`. A live shell export takes precedence over a
|
|
156
|
-
persisted value; the house-class isolation vars (`HOME`, `CLAUDE_CONFIG_DIR`,
|
|
157
|
-
class) always win over both. Apply a change to an already-running stack with
|
|
158
|
-
`cabane down && cabane up`.
|
|
154
|
+
The self-hosted server needs no model credential of its own. `cabane set-env` stays
|
|
155
|
+
for any generic server env you _do_ want to persist:
|
|
156
|
+
|
|
157
|
+
```sh
|
|
158
|
+
# persisted — save once; every future `up` (fresh shell, reboot) picks it up.
|
|
159
|
+
# A bare KEY prompts for the value (hidden); `KEY=VALUE` still works for scripting.
|
|
160
|
+
cabane set-env SOME_KEY
|
|
161
|
+
cabane down && cabane up --daemon
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
It stores generic `KEY=VALUE` pairs in `<CABANE_HOME>/config.json` and layers them
|
|
165
|
+
into the server's env on every `up` — beneath the composed infra vars, so an
|
|
166
|
+
operator key reaches the server but can never clobber `DATABASE_URL` / `NODE_ENV` /
|
|
167
|
+
`STORAGE_*`. A bare `cabane set-env KEY` (no `=value`) prompts for the value without
|
|
168
|
+
echoing, so a secret never lands on the command line. Inspect with
|
|
169
|
+
`cabane set-env --list` (values masked), remove with `cabane set-env --unset KEY`.
|
|
170
|
+
A live shell export takes precedence over a persisted value. Apply a change to an
|
|
171
|
+
already-running stack with `cabane down && cabane up`.
|
|
159
172
|
|
|
160
173
|
## Notes
|
|
161
174
|
|
|
162
|
-
- **macOS Gatekeeper**
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
- **Install the _server_ artifact from a local build** with `cabane install --from <artifact.tgz>` instead of a distribution token — handy for an offline or air-gapped install.
|
|
175
|
+
- **macOS Gatekeeper** may quarantine the unsigned Postgres binaries. If pg
|
|
176
|
+
fails to exec on first run, clear the quarantine xattr and retry —
|
|
177
|
+
`cabane doctor` detects this and prints the fix.
|