chattrs 0.5.0 → 0.7.0
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 +274 -68
- package/npm-shrinkwrap.json +2 -2
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -25,55 +25,193 @@ over TCP, so a script in any language can join too.
|
|
|
25
25
|
|
|
26
26
|
## Get running
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
`chattrs exec claude` starts an agent on the swarm. It sets the address
|
|
29
|
+
and the session, then hands the process to the agent. chattrs never hosts
|
|
30
|
+
or supervises the agent. For other launchers (Herdr, tmux, scripts), use
|
|
31
|
+
`chattrs env`, which prints the same settings as `export` lines.
|
|
32
|
+
|
|
33
|
+
`exec` does not put the token in the agent's environment. Each chattrs
|
|
34
|
+
call in the agent reads the token from `config.toml`, as the hooks do. An
|
|
35
|
+
explicit `CHATTRS_TOKEN` in your shell passes through unchanged. If no
|
|
36
|
+
token is found, `exec` prints `chattrs: no token for ADDR; the broker may
|
|
37
|
+
refuse` and still starts the agent.
|
|
38
|
+
|
|
39
|
+
The broker refuses a second live session for the same address (ID-1). The
|
|
40
|
+
refusal shows when the agent's hooks or `watch` connect.
|
|
41
|
+
|
|
42
|
+
#### Start an agent on another host
|
|
29
43
|
|
|
30
|
-
|
|
44
|
+
`chattrs exec --host H [--cwd DIR] [--detach] [--session-name NAME] PROGRAM`
|
|
45
|
+
starts the agent on host `H`. It runs the system `ssh`, so `~/.ssh/config`
|
|
46
|
+
aliases work. The remote login shell runs `chattrs exec` there.
|
|
31
47
|
|
|
32
48
|
```bash
|
|
33
|
-
|
|
34
|
-
chattrs
|
|
35
|
-
mkdir -p ~/.claude/skills/chattrs && chattrs skill > ~/.claude/skills/chattrs/SKILL.md
|
|
49
|
+
chattrs exec --host bobox --cwd ~/repo --as w1@bobox --lead lead@mac codex
|
|
50
|
+
chattrs exec --host bobox --cwd ~/repo --detach --as w1@bobox --lead lead@mac codex
|
|
36
51
|
```
|
|
37
52
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
53
|
+
- chattrs forwards only `--as`, `--lead`, the program, and its arguments.
|
|
54
|
+
It never sends the token, the server, the project, the tags, or any
|
|
55
|
+
`CHATTRS_*` variable. The remote host reads its own config and token.
|
|
56
|
+
- The remote host needs `chattrs` on its login-shell `PATH` and its own
|
|
57
|
+
config and token (`chattrs setup --join`).
|
|
58
|
+
- Without `--detach`, the worker lives only as long as the ssh connection.
|
|
59
|
+
If the launching machine sleeps, loses the network, or closes the
|
|
60
|
+
terminal, the worker stops.
|
|
61
|
+
- With `--detach`, the worker runs in a remote tmux session and chattrs
|
|
62
|
+
returns. The worker lives until it exits or someone kills the session.
|
|
63
|
+
chattrs prints the attach command (`ssh -t H tmux attach -t NAME`) and
|
|
64
|
+
the stop command (`ssh H tmux kill-session -t NAME`). `NAME` defaults to
|
|
65
|
+
the user part of the address, with unsafe characters turned into `-`.
|
|
66
|
+
- tmux is optional. Only `--detach` needs it. If tmux is missing, chattrs
|
|
67
|
+
exits 1 and says so. It never installs tmux, never falls back to a run
|
|
68
|
+
without `--detach`, and never attaches to or kills an existing session.
|
|
69
|
+
- chattrs never watches, kills, or restarts agents.
|
|
41
70
|
|
|
42
|
-
|
|
43
|
-
address, a session, and the lead. Nothing else is needed.
|
|
71
|
+
### Solo, one machine
|
|
44
72
|
|
|
45
|
-
|
|
46
|
-
# Terminal 1
|
|
47
|
-
eval "$(chattrs env --as lead@mac)" && claude
|
|
73
|
+
Three steps.
|
|
48
74
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
75
|
+
1. Install chattrs. On macOS: `brew install bolu-atx/tap/chattrs`. For
|
|
76
|
+
npm or cargo, see [Install](#install).
|
|
77
|
+
2. Set up the agents once:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
chattrs setup
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`setup` finds Claude Code and Codex. For each one it installs the hooks
|
|
84
|
+
and the skill. It writes `~/.config/chattrs/config.toml` only when none
|
|
85
|
+
exists. It is safe to run again. Then follow the printed trust steps:
|
|
86
|
+
open Codex once and run `/hooks` to trust the new hooks. Claude Code may
|
|
87
|
+
ask you to review the hooks.
|
|
88
|
+
3. Start a lead and a worker in two terminals:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
# Terminal 1
|
|
92
|
+
chattrs exec --as lead@mac claude
|
|
93
|
+
|
|
94
|
+
# Terminal 2
|
|
95
|
+
chattrs exec --as w1@mac --lead lead@mac codex
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Without `--as`, the address is `<program>@<host>`, for example
|
|
99
|
+
`claude@mac`. Arguments after the program go to the program:
|
|
100
|
+
`chattrs exec claude --resume ID`.
|
|
52
101
|
|
|
53
102
|
The first command starts a loopback broker on its own. The session-start
|
|
54
|
-
hook tells each agent its address and its lead, and to load the skill.
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
runs `chattrs watch`.
|
|
103
|
+
hook tells each agent its address and its lead, and to load the skill.
|
|
104
|
+
Ask the lead to send w1 a task. Run `chattrs agents` to see both agents.
|
|
105
|
+
An agent shows `online` only while it runs `chattrs watch`. Hooks deliver
|
|
106
|
+
messages between tool calls. In Claude Code, the agent runs `chattrs
|
|
107
|
+
watch` under Monitor, so a message wakes it.
|
|
60
108
|
|
|
61
109
|
### Swarm, several machines
|
|
62
110
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
`
|
|
76
|
-
|
|
111
|
+
Five steps. Use a broker host that is always on. A laptop sleeps, and the
|
|
112
|
+
swarm stops. Install and run `chattrs setup` on every host first, as in
|
|
113
|
+
the solo path.
|
|
114
|
+
|
|
115
|
+
1. On the broker host, issue tokens and write the service unit:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
chattrs setup --broker --hosts mac,bobox --bind 100.64.0.1 --enable
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`--hosts` lists the agent hosts. `--bind` is the tailnet or LAN IP. It
|
|
122
|
+
defaults to the Tailscale IPv4. It never takes `0.0.0.0` or `::`.
|
|
123
|
+
`--enable` starts the service. The command prints one join string for
|
|
124
|
+
each token.
|
|
125
|
+
2. Copy each host's join string to that host, over a private channel. A
|
|
126
|
+
join string holds a token. Treat it like a password. The broker never
|
|
127
|
+
stores it.
|
|
128
|
+
3. On each host, run `setup --join` and paste the join strings on stdin.
|
|
129
|
+
End with Ctrl-D. This keeps them out of shell history:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
chattrs setup --join -
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
It writes a token file (mode 0600) and one `[tokens]` entry in
|
|
136
|
+
`~/.config/chattrs/config.toml`, and it sets `server`. A host that runs
|
|
137
|
+
agents next to the broker needs this step too. The lead host needs
|
|
138
|
+
the lead's join string as well.
|
|
139
|
+
4. On each host, check the setup:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
chattrs doctor --as w1@bobox
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Each check prints `ok` or `FAIL` with a fix hint. The command exits 1
|
|
146
|
+
on any failure.
|
|
147
|
+
5. Launch every agent with its own address:
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
chattrs exec --as lead@mac claude
|
|
151
|
+
chattrs exec --as w1@bobox --lead lead@mac codex
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
`env --as` exports the address, a new session id, and the server. It does
|
|
155
|
+
not print the token. Each command then reads the token from the `[tokens]`
|
|
156
|
+
entry that matches the address. To set the project for all hosts, commit a
|
|
157
|
+
`.chattrs.toml` in the repo ([Environment and config](#environment-and-config)).
|
|
158
|
+
|
|
159
|
+
### Several hosts: `setup --broker` and `setup --join` (SETUP-2)
|
|
160
|
+
|
|
161
|
+
Reference for steps 1 to 3 above.
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
chattrs setup --broker --hosts <a,b> [--lead lead@mac] [--projects p1,p2] \
|
|
165
|
+
[--bind <ip>] [--port 4646] [--enable]
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
It writes `~/.config/chattrs/tokens.toml` (mode 0600) and a systemd user unit
|
|
169
|
+
(`~/.config/systemd/user/chattrs.service`) or a launchd plist
|
|
170
|
+
(`~/Library/LaunchAgents/com.chattrs.broker.plist`). It never overwrites
|
|
171
|
+
either file. It prints the command that starts the service; `--enable` runs
|
|
172
|
+
it. It issues one agent token per host (`*@<host>`), one lead token, and one
|
|
173
|
+
observer token (`tray@*`). The tokens have no `project` line, so they work in
|
|
174
|
+
every project. With `--projects`, it writes one entry per project instead,
|
|
175
|
+
and each token stays inside those projects (the observer still sees all).
|
|
176
|
+
Then it prints one join string for each, `chattrs://<token>@<ip>:<port>?as=<pattern>`. The pattern is
|
|
177
|
+
percent-encoded.
|
|
178
|
+
|
|
179
|
+
`setup --join` also takes a string as an argument. Quote it, but it then
|
|
180
|
+
stays in shell history:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
chattrs setup --join 'chattrs://TOKEN@100.64.0.1:4646?as=lead%40mac'
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`--join` is repeatable, and stdin can carry one string per line. A string
|
|
187
|
+
without `?as=` needs `--as <pattern>` (one string only). Each string writes
|
|
188
|
+
`~/.config/chattrs/<name>.token` (mode 0600). The name is the pattern with
|
|
189
|
+
`@` as `-` and `*` as `any`: `lead@mac` gives `lead-mac.token`,
|
|
190
|
+
`*@bobox` gives `any-bobox.token`. The command sets `server` when it is
|
|
191
|
+
missing, and it refuses a different `server`. It keeps all other lines. It
|
|
192
|
+
refuses a pattern that already has an entry or a file; `--force` replaces
|
|
193
|
+
them. Then it runs the plain `setup`. The project is not in the join
|
|
194
|
+
string; it comes from `.chattrs.toml`, else `default`.
|
|
195
|
+
|
|
196
|
+
### Check a host: `doctor` (SETUP-3)
|
|
197
|
+
|
|
198
|
+
Reference for step 4 above. Run `chattrs doctor` in the environment of an
|
|
199
|
+
agent (with `CHATTRS_ADDRESS` set, or pass `--as`). It prints one line per
|
|
200
|
+
check, `ok <check>: ...` or `FAIL <check>: ... <fix hint>`, and exits 1 on
|
|
201
|
+
any failure. It checks the config files, the token file each identity uses
|
|
202
|
+
(mode 0600), that the broker accepts a connection, that the broker accepts
|
|
203
|
+
the token for the project and address, the protocol version, the hooks, and
|
|
204
|
+
the skill text. It never prints a token. It writes no file and reads no
|
|
205
|
+
message. The token check sends one normal `hello` as the current address,
|
|
206
|
+
with `CHATTRS_SESSION`, so the broker logs no rejection. It shows the project
|
|
207
|
+
and the broker version from the `welcome`. The `hello` updates the last-seen
|
|
208
|
+
of the current address, so that address looks active to health for a moment.
|
|
209
|
+
This is known and not fixed. Other `[tokens]` identities are listed and not
|
|
210
|
+
probed. Without a current address, doctor checks only that the broker accepts
|
|
211
|
+
a connection and prints a warning. Without `CHATTRS_SESSION`, doctor says
|
|
212
|
+
`hello` without a session and prints a note: use `chattrs env`. A `tray@`
|
|
213
|
+
identity says an observer `hello`. Codex hook trust cannot be detected, so
|
|
214
|
+
doctor always ends with a reminder to trust the hooks in `/hooks` in Codex.
|
|
77
215
|
|
|
78
216
|
## Install
|
|
79
217
|
|
|
@@ -90,6 +228,8 @@ build (DIST-1).
|
|
|
90
228
|
|
|
91
229
|
## Quick start
|
|
92
230
|
|
|
231
|
+
This is the raw CLI on one machine, with no agent. For agents, see [Get running](#get-running).
|
|
232
|
+
|
|
93
233
|
One machine, no broker terminal. The first command starts a loopback broker
|
|
94
234
|
on `127.0.0.1:4646`. The broker logs to `chattrs.log` and writes its pid to
|
|
95
235
|
`chattrs.pid`, both next to the DB. `chattrs stop` ends it.
|
|
@@ -127,7 +267,7 @@ that holds `</agent-message` is escaped, so it cannot close the wrapper.
|
|
|
127
267
|
|
|
128
268
|
## Commands
|
|
129
269
|
|
|
130
|
-
Every command except `serve`, `stop`, `skill`, `env`, and `hooks` takes the
|
|
270
|
+
Every command except `serve`, `stop`, `skill`, `env`, `setup`, `doctor`, and `hooks` takes the
|
|
131
271
|
[common flags](#environment-and-config). Every one except `status`, `projects`,
|
|
132
272
|
`hook`, and `watch` first prints unread messages, then its own output, and
|
|
133
273
|
acks them (MSG-5). Announcements never reach an inbox.
|
|
@@ -145,7 +285,10 @@ acks them (MSG-5). Announcements never reach an inbox.
|
|
|
145
285
|
| `agents [--all] [--json]` | List the agents of the project: online or last seen, state, health, tags. Hides agents offline over 7 days with no traffic since. `--all` shows them. |
|
|
146
286
|
| `projects [--json]` | List every project with its agent and message counts. Read-only. |
|
|
147
287
|
| `status working\|idle\|waiting` | Report the own state. Best effort: it never starts a broker, gives up after about 2 s, and always exits 0. |
|
|
288
|
+
| `exec [--as ADDR] [--project P] [--lead ADDR] [--server S] [--tags T] [--host H [--cwd DIR] [--detach [--session-name N]]] [--] PROGRAM [ARGS...]` | Run PROGRAM with the session env that `env` prints. On Unix it replaces the chattrs process. The default address is `<program>@<host>`. It never adds the token to the environment. With `--host` it runs the same command on H over `ssh`, see [Start an agent on another host](#start-an-agent-on-another-host). |
|
|
148
289
|
| `env --as ADDR [--project P] [--lead ADDR] [--server S] [--tags T] [--token T] [--with-token]` | Print `export` lines for one session: `eval "$(chattrs env --as a@h)"`. It makes a new `CHATTRS_SESSION` on every run. It omits the token unless `--with-token`. |
|
|
290
|
+
| `setup` | Install the hooks and the skill for each agent found (Claude Code, Codex). Write a starter `config.toml` only if missing. Safe to run again. `setup --broker --hosts a,b [...]` prepares a broker host; `setup --join STRING\|-` stores join-string tokens. See [Several hosts](#several-hosts-setup---broker-and-setup---join-setup-2). |
|
|
291
|
+
| `doctor [--as ADDR] [--server S]` | Check config, token files, broker, token, protocol, hooks, and skill. One `ok` or `FAIL` line each; exit 1 on any failure. Read-only. See [Check a host](#check-a-host-doctor-setup-3). |
|
|
149
292
|
| `hooks install\|remove [--agent claude\|codex\|all] [--project]` | Edit the hook entries in the agent configs. See [Hooks](#hooks-claude-code-and-codex). |
|
|
150
293
|
| `hook EVENT` | Run as a hook. Reads hook JSON on stdin. Not for direct use. |
|
|
151
294
|
| `skill` | Print the bundled agent skill. Needs no connection or address. |
|
|
@@ -178,6 +321,24 @@ is an error that names the file and line. The repo file holds no secrets: a
|
|
|
178
321
|
that holds only the token. On unix it must have mode 0600 or tighter. The
|
|
179
322
|
token applies when neither `CHATTRS_TOKEN` nor `--token` is set.
|
|
180
323
|
|
|
324
|
+
One host can hold several identities (SETUP-4). A `[tokens]` table in the
|
|
325
|
+
user config maps an address or a glob to its own token file:
|
|
326
|
+
|
|
327
|
+
```toml
|
|
328
|
+
token_file = "/home/me/.config/chattrs/token" # fallback
|
|
329
|
+
[tokens]
|
|
330
|
+
"lead@mac" = "/home/me/.config/chattrs/lead-token"
|
|
331
|
+
"*@mac" = "/home/me/.config/chattrs/mac-token"
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
The token for an address comes from the first of these that applies:
|
|
335
|
+
`CHATTRS_TOKEN` or `--token`; the `[tokens]` entry that matches the address
|
|
336
|
+
(an exact address beats a glob, and among globs the longest pattern wins);
|
|
337
|
+
the plain `token_file`. The address is `--as`, `--address`, or `--agent`,
|
|
338
|
+
then `CHATTRS_ADDRESS`, then `CHATTRS_AGENT`. `chattrs env --as ADDR
|
|
339
|
+
--with-token` prints the token for ADDR. The table is only in the user
|
|
340
|
+
config, never in `.chattrs.toml`.
|
|
341
|
+
|
|
181
342
|
```toml
|
|
182
343
|
# ~/.config/chattrs/config.toml
|
|
183
344
|
server = "10.0.0.5:4646"
|
|
@@ -214,13 +375,15 @@ Tags come from the latest `hello`. A command run from another shell without
|
|
|
214
375
|
## Teach workers the skill
|
|
215
376
|
|
|
216
377
|
`chattrs skill` prints the worker skill (`skills/chattrs/SKILL.md`).
|
|
378
|
+
`chattrs setup` installs it for Claude Code and Codex. To install it by
|
|
379
|
+
hand:
|
|
217
380
|
|
|
218
381
|
```bash
|
|
219
382
|
mkdir -p ~/.claude/skills/chattrs && chattrs skill > ~/.claude/skills/chattrs/SKILL.md
|
|
220
383
|
```
|
|
221
384
|
|
|
222
|
-
For pi, pass that directory with `--skill`.
|
|
223
|
-
|
|
385
|
+
For pi, pass that directory with `--skill`. Muse has no skill directory:
|
|
386
|
+
the lead puts `$(chattrs skill)` in the worker's prompt.
|
|
224
387
|
|
|
225
388
|
Give each worker a unique address. Two agents on one address share an
|
|
226
389
|
inbox. There is no default agent name.
|
|
@@ -248,15 +411,18 @@ holder every project and every address. Use it for a quick test only.
|
|
|
248
411
|
### Keep the database
|
|
249
412
|
|
|
250
413
|
Put `CHATTRS_DB` (or `--db`) on persistent disk. The broker never deletes a
|
|
251
|
-
message, so the database is the swarm's history. Back it up with
|
|
252
|
-
never with `cp` on a live database
|
|
414
|
+
message, so the database is the swarm's history. Back it up with
|
|
415
|
+
`chattrs backup`, never with `cp` on a live database. It works while the
|
|
416
|
+
broker runs and refuses to replace a file unless you pass `--force`:
|
|
253
417
|
|
|
254
418
|
```bash
|
|
255
|
-
|
|
419
|
+
chattrs backup <file> [--db <db>] [--force]
|
|
256
420
|
```
|
|
257
421
|
|
|
258
422
|
### Run the broker as a service
|
|
259
423
|
|
|
424
|
+
`chattrs setup --broker` writes these units for you ([Get running](#get-running)). Use this section to write them by hand.
|
|
425
|
+
|
|
260
426
|
Linux: put a `systemd --user` unit in
|
|
261
427
|
`~/.config/systemd/user/chattrs.service`.
|
|
262
428
|
|
|
@@ -315,6 +481,8 @@ for an unattended Mac.
|
|
|
315
481
|
|
|
316
482
|
### Set client hosts
|
|
317
483
|
|
|
484
|
+
`chattrs setup --join` does this for you ([Get running](#get-running)). Use this section to edit the config by hand.
|
|
485
|
+
|
|
318
486
|
On every client host, set the broker address and the token file in the user
|
|
319
487
|
config (see [Environment and config](#environment-and-config)):
|
|
320
488
|
|
|
@@ -330,17 +498,28 @@ second, auto-started broker, and that agent then joins a different swarm.
|
|
|
330
498
|
|
|
331
499
|
### Start a worker
|
|
332
500
|
|
|
333
|
-
The lead starts each worker
|
|
334
|
-
|
|
335
|
-
`.chattrs.toml`
|
|
336
|
-
and lead exist only in the launch line:
|
|
501
|
+
The lead starts each worker with `chattrs exec --host`. The worker needs no
|
|
502
|
+
flags. The host config has the server and token file. The project is the
|
|
503
|
+
repo name, and the repo's `.chattrs.toml` can set the lead:
|
|
337
504
|
|
|
338
505
|
```bash
|
|
339
|
-
|
|
506
|
+
chattrs exec --host <host> --cwd ~/repo --detach --as worker1@<host> --lead opus@mac claude "Your address is worker1@<host>. Your lead is opus@mac. Run chattrs watch under the Monitor tool now."
|
|
340
507
|
```
|
|
341
508
|
|
|
509
|
+
`--detach` starts the worker in a tmux session on the host and prints how
|
|
510
|
+
to attach and stop it. Without `--detach`, the worker lives only as long as
|
|
511
|
+
the ssh connection: if the launching machine sleeps, loses network, or
|
|
512
|
+
closes the terminal, the worker stops.
|
|
513
|
+
|
|
342
514
|
On the host itself:
|
|
343
515
|
|
|
516
|
+
```bash
|
|
517
|
+
chattrs exec --as worker1@box claude "..."
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
For other launchers (Herdr, tmux, scripts), `chattrs env` prints the same
|
|
521
|
+
settings as shell exports:
|
|
522
|
+
|
|
344
523
|
```bash
|
|
345
524
|
tmux new -d -s w1 'eval "$(chattrs env --as worker1@box)"; exec claude "..."'
|
|
346
525
|
```
|
|
@@ -385,43 +564,50 @@ Run this once on a new swarm.
|
|
|
385
564
|
|
|
386
565
|
### Token table
|
|
387
566
|
|
|
388
|
-
Meets SEC-4. A token table gives each token
|
|
389
|
-
|
|
567
|
+
Meets SEC-4. A token table gives each token an address pattern and a role.
|
|
568
|
+
A token works in every project. An optional `project` line limits it to one
|
|
569
|
+
project. Start the broker with `serve --tokens <path>` or
|
|
390
570
|
`CHATTRS_TOKENS`. The file is TOML. The broker refuses to start when its
|
|
391
571
|
mode is wider than 0600 (unix). Make each token with `openssl rand -hex 32`.
|
|
392
572
|
|
|
393
573
|
```toml
|
|
394
|
-
# The lead
|
|
574
|
+
# The lead. Only a lead token can claim this address, in any project.
|
|
395
575
|
[[token]]
|
|
396
576
|
token = "<64 hex characters>"
|
|
397
|
-
project = "alpha"
|
|
398
577
|
addr = "lead@box1"
|
|
399
578
|
role = "lead"
|
|
400
579
|
|
|
401
|
-
# Any worker on box1, in
|
|
580
|
+
# Any worker on box1, in every project.
|
|
402
581
|
[[token]]
|
|
403
582
|
token = "<64 hex characters>"
|
|
404
|
-
project = "alpha"
|
|
405
583
|
addr = "*@box1"
|
|
406
584
|
role = "agent"
|
|
407
585
|
|
|
586
|
+
# A worker on box2, walled into project alpha.
|
|
587
|
+
[[token]]
|
|
588
|
+
token = "<64 hex characters>"
|
|
589
|
+
project = "alpha"
|
|
590
|
+
addr = "*@box2"
|
|
591
|
+
role = "agent"
|
|
592
|
+
|
|
408
593
|
# A read-only viewer that sees every project.
|
|
409
594
|
[[token]]
|
|
410
595
|
token = "<64 hex characters>"
|
|
411
|
-
project = "*"
|
|
412
596
|
addr = "tray@mac"
|
|
413
597
|
role = "observer"
|
|
414
598
|
```
|
|
415
599
|
|
|
416
600
|
The parser reads a small subset of TOML: blank lines, `#` comments,
|
|
417
601
|
`[[token]]` headers, and `key = "value"` lines (double quotes, no escapes).
|
|
418
|
-
The keys `token`, `
|
|
419
|
-
Any other line, an unknown key,
|
|
420
|
-
broker with an error that names the line. A
|
|
421
|
-
|
|
422
|
-
project
|
|
423
|
-
|
|
424
|
-
|
|
602
|
+
The keys `token`, `addr`, and `role` are required. `project` is optional.
|
|
603
|
+
Each key appears once per entry. Any other line, an unknown key, or a bad
|
|
604
|
+
value stops the broker with an error that names the line. A repeated token
|
|
605
|
+
stops it too, unless every copy names a different project. A lead who
|
|
606
|
+
leads several projects can use one entry with no `project`, or one token
|
|
607
|
+
listed once per project.
|
|
608
|
+
|
|
609
|
+
- `project` is a project name. With no `project`, the token works in every
|
|
610
|
+
project. `"*"` means the same, for `observer` entries only (the old form).
|
|
425
611
|
- `addr` is an exact address, or a pattern where `*` matches any run of
|
|
426
612
|
characters, such as `*@box1`.
|
|
427
613
|
- `role` is `lead`, `agent`, or `observer`.
|
|
@@ -431,9 +617,10 @@ time, then checks the hello:
|
|
|
431
617
|
|
|
432
618
|
- No entry matches: `bad_token`. The broker closes the connection.
|
|
433
619
|
- The project or address does not fit the entry, or a role rule fails:
|
|
434
|
-
`forbidden`.
|
|
620
|
+
`forbidden`. The project check applies only to an entry with a `project`.
|
|
435
621
|
- Lead rule: only a `lead` entry can claim an address that a `lead` entry
|
|
436
|
-
names exactly in that
|
|
622
|
+
names exactly. This holds in every project, whether or not that entry
|
|
623
|
+
has a `project`.
|
|
437
624
|
- Observer rule: an `observer` entry works only with an observer hello. An
|
|
438
625
|
`agent` entry cannot send an observer hello.
|
|
439
626
|
|
|
@@ -455,12 +642,14 @@ Rules:
|
|
|
455
642
|
|
|
456
643
|
#### Turning on per-host tokens
|
|
457
644
|
|
|
645
|
+
This is for a swarm that already runs on the shared token. A new swarm uses `chattrs setup --broker` instead.
|
|
646
|
+
|
|
458
647
|
Once a tokens file exists, the broker refuses the shared token. Switching
|
|
459
648
|
everything at once breaks every client at the same moment. Use two phases.
|
|
460
649
|
|
|
461
650
|
Phase 1: a plain upgrade.
|
|
462
651
|
|
|
463
|
-
1. Back up the database: `
|
|
652
|
+
1. Back up the database: `chattrs backup <file> --db <db>`.
|
|
464
653
|
2. Upgrade the broker. Start it with no tokens file. Legacy mode stays on.
|
|
465
654
|
3. Check that workers and viewers still connect.
|
|
466
655
|
|
|
@@ -489,9 +678,23 @@ another project lands in the sender's project, with `known:false`. The same
|
|
|
489
678
|
address in two projects is two agents (NS-1). A client with no project uses
|
|
490
679
|
`default`.
|
|
491
680
|
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
681
|
+
A client picks its project in this order. The first match wins:
|
|
682
|
+
|
|
683
|
+
1. `CHATTRS_PROJECT` or `--project`.
|
|
684
|
+
2. `project` in `.chattrs.toml` or `~/.config/chattrs/config.toml`.
|
|
685
|
+
3. The repo name, when the directory is inside a git repo.
|
|
686
|
+
4. `default`.
|
|
687
|
+
|
|
688
|
+
The repo name is the last part of the `origin` URL, without `.git`. With no
|
|
689
|
+
`origin`, it is the name of the directory that holds the repo. A worktree
|
|
690
|
+
has the same name as its main repo. The name is lowercase, and every
|
|
691
|
+
character outside `a-z` and `0-9` becomes `-`. `chattrs doctor` and
|
|
692
|
+
`chattrs env` print the project and its source.
|
|
693
|
+
|
|
694
|
+
Upgrade note: a session inside a repo now joins the repo project, not
|
|
695
|
+
`default`. A token table that allows only `default` rejects it. Add the repo
|
|
696
|
+
project to `tokens.toml`, or pin `project` in `.chattrs.toml`. Doctor then
|
|
697
|
+
says `token not valid for project <name> (derived from git)`.
|
|
495
698
|
|
|
496
699
|
```bash
|
|
497
700
|
export CHATTRS_PROJECT=alpha
|
|
@@ -589,7 +792,7 @@ Client to broker:
|
|
|
589
792
|
Broker to client:
|
|
590
793
|
|
|
591
794
|
```json
|
|
592
|
-
{"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1", "project":"alpha"}
|
|
795
|
+
{"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1", "project":"alpha", "version":"0.6.0"}
|
|
593
796
|
{"type":"sent", "id":12} // optional "known":false: `to` never said hello
|
|
594
797
|
{"type":"inbox", "messages":[
|
|
595
798
|
{"id":12,"from":"codex@box1","to":"opus@mac",
|
|
@@ -623,6 +826,9 @@ carries a token, loopback too. Optional `hello` fields:
|
|
|
623
826
|
15 minutes as `unknown` (MON-4). `chattrs status` sends such a `hello`.
|
|
624
827
|
- `observer`: see [Monitoring](#monitoring-api-observer).
|
|
625
828
|
|
|
829
|
+
`welcome` carries `"version"`, the broker's crate version. It is optional:
|
|
830
|
+
an older broker omits it, and an older client ignores it. `doctor` shows it.
|
|
831
|
+
|
|
626
832
|
`welcome` may carry `"watching":true` when the address already has a live
|
|
627
833
|
inbox `watch`. The `watch` command then warns once on stderr and keeps
|
|
628
834
|
going.
|
package/npm-shrinkwrap.json
CHANGED
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"hasInstallScript": true,
|
|
20
20
|
"license": "MIT",
|
|
21
21
|
"name": "chattrs",
|
|
22
|
-
"version": "0.
|
|
22
|
+
"version": "0.7.0"
|
|
23
23
|
},
|
|
24
24
|
"node_modules/detect-libc": {
|
|
25
25
|
"engines": {
|
|
@@ -48,5 +48,5 @@
|
|
|
48
48
|
}
|
|
49
49
|
},
|
|
50
50
|
"requires": true,
|
|
51
|
-
"version": "0.
|
|
51
|
+
"version": "0.7.0"
|
|
52
52
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"artifactDownloadUrls": [
|
|
3
|
-
"https://github.com/bolu-atx/chattrs/releases/download/v0.
|
|
3
|
+
"https://github.com/bolu-atx/chattrs/releases/download/v0.7.0"
|
|
4
4
|
],
|
|
5
5
|
"bin": {
|
|
6
6
|
"chattrs": "run-chattrs.js"
|
|
@@ -79,7 +79,7 @@
|
|
|
79
79
|
"zipExt": ".tar.xz"
|
|
80
80
|
}
|
|
81
81
|
},
|
|
82
|
-
"version": "0.
|
|
82
|
+
"version": "0.7.0",
|
|
83
83
|
"volta": {
|
|
84
84
|
"node": "18.14.1",
|
|
85
85
|
"npm": "9.5.0"
|