shapewall 0.3.3 → 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/CHANGELOG.md +501 -0
- package/README.md +87 -4
- package/THIRD_PARTY.md +15 -0
- package/dist/agent/package-lock.json +594 -2
- package/dist/client/assets/BoardChat-WS8mAIW6.js +27 -0
- package/dist/client/assets/{BuzzDialog-Ix9qJvim.js → BuzzDialog-B-Mlr6wF.js} +1 -1
- package/dist/client/assets/ChecksPanel-Dx1ZLBR6.js +1 -0
- package/dist/client/assets/History-sXhmpcvs.js +1 -0
- package/dist/client/assets/LocalSettings-CtGzz9F3.js +1 -0
- package/dist/client/assets/{Management-NVFDtSZB.js → Management-CGHe8Wt9.js} +1 -1
- package/dist/client/assets/QuickConnect-DEk84E4A.js +1 -0
- package/dist/client/assets/{ShareDialog-By0ETg6n.js → ShareDialog-CGGx-AYK.js} +2 -2
- package/dist/client/assets/{app-update-dialog-RGIw24iZ.js → app-update-dialog-_bVp8hnC.js} +1 -1
- package/dist/client/assets/{circle-x-B6KfScOE.js → circle-x-BWoHA1QY.js} +1 -1
- package/dist/client/assets/index-Bm-Xd3YN.js +37 -0
- package/dist/client/assets/index-C7Ostk3K.css +2 -0
- package/dist/client/assets/play-BzQ3tRTv.js +1 -0
- package/dist/client/assets/{refresh-cw-vkgvCCfR.js → refresh-cw-BYBMyDKT.js} +1 -1
- package/dist/client/assets/{runtime-Bft6x_6E.js → runtime-Bvq10IhH.js} +1 -1
- package/dist/client/assets/ui-CAY6myRA.js +41 -0
- package/dist/client/build-info.json +1 -1
- package/dist/client/index.html +3 -3
- package/dist/client/sw.js +2 -2
- package/dist/console/assets/LocalAccountsApp-CWRguRRL.js +1 -0
- package/dist/console/assets/LocalConsole--I2SaIpr.js +2 -0
- package/dist/console/assets/LocalUsage-BmpCZ36k.js +1 -0
- package/dist/console/assets/app-update-dialog-B8M9plaT.js +1 -0
- package/dist/console/assets/app-version-muKrQqbL.js +1 -0
- package/dist/console/assets/console-CrhTsPbz.css +2 -0
- package/dist/console/assets/console-DxapQ9oS.js +11 -0
- package/dist/console/assets/local-agents-CoqD4dSN.js +6 -0
- package/dist/console/assets/minus-DDQ0ydcM.js +1 -0
- package/dist/console/assets/tailnet-C5Flwl_d.js +2 -0
- package/dist/console/assets/theme-DCd0qh4l.js +1 -0
- package/dist/console/assets/ui-Bry1mnCY.js +41 -0
- package/dist/console/assets/usage-CIPWnHaS.css +1 -0
- package/dist/console/assets/usage-CqVjMb7m.js +5 -0
- package/dist/console/assets/usage-D1G0GgE3.js +56 -0
- package/dist/console/build-info.json +1 -1
- package/dist/console/console.html +8 -2
- package/docs/agent-hardening.md +206 -0
- package/docs/agent-recipes.md +23 -0
- package/docs/agent-workflow.md +5 -0
- package/docs/agents.md +49 -6
- package/docs/architecture.md +10 -4
- package/docs/deployment.md +39 -17
- package/docs/design-system.md +56 -7
- package/docs/hosted.md +1800 -46
- package/docs/images/board-overview.png +0 -0
- package/docs/images/journeys.png +0 -0
- package/docs/images/live-comment.png +0 -0
- package/docs/images/phone-comment.png +0 -0
- package/docs/images/phone-overview.png +0 -0
- package/docs/images/variant.png +0 -0
- package/docs/where-to-run.md +119 -3
- package/package.json +6 -1
- package/src/agent/backends/acp.js +745 -44
- package/src/agent/branch-mode.js +17 -3
- package/src/agent/card-hash.js +65 -0
- package/src/agent/context.js +41 -0
- package/src/agent/exec-paths.js +105 -0
- package/src/agent/routes.js +23 -2
- package/src/agent/run.js +11 -1
- package/src/agent/starter/cli.js +6 -1
- package/src/agent/turn-changes.js +70 -8
- package/src/agent/usage-log.js +251 -0
- package/src/cli/args.js +37 -0
- package/src/cli/commands.js +20 -5
- package/src/cli/help.js +73 -3
- package/src/cli/init.js +2 -1
- package/src/cli/serve.js +20 -5
- package/src/cli.js +8 -0
- package/src/hosted/access-cli.js +99 -1
- package/src/hosted/activity-core.js +232 -0
- package/src/hosted/activity.js +375 -0
- package/src/hosted/admin.js +87 -13
- package/src/hosted/agent-approvals.js +29 -4
- package/src/hosted/agent-link.js +1032 -0
- package/src/hosted/agent-policy.js +10 -3
- package/src/hosted/agent-presence.js +63 -22
- package/src/hosted/agent-routes.js +135 -0
- package/src/hosted/agents.js +1206 -0
- package/src/hosted/app.js +178 -12
- package/src/hosted/auth-routes.js +156 -15
- package/src/hosted/auth.js +123 -20
- package/src/hosted/board-routes.js +129 -5
- package/src/hosted/chat-frames.js +246 -0
- package/src/hosted/chat-job.js +204 -0
- package/src/hosted/chat-permissions.js +203 -0
- package/src/hosted/chat-routes.js +1009 -0
- package/src/hosted/chat-store.js +477 -0
- package/src/hosted/comment-files.js +11 -1
- package/src/hosted/comments.js +1 -1
- package/src/hosted/console-routes.js +122 -34
- package/src/hosted/db.js +295 -0
- package/src/hosted/device-routes.js +88 -10
- package/src/hosted/device.js +54 -4
- package/src/hosted/events.js +3 -3
- package/src/hosted/guards.js +337 -27
- package/src/hosted/http.js +6 -3
- package/src/hosted/membership.js +22 -3
- package/src/hosted/operator-access.js +418 -0
- package/src/hosted/operator.js +106 -2
- package/src/hosted/ops-cli.js +238 -3
- package/src/hosted/pages.js +4 -0
- package/src/hosted/passkey-policy.js +75 -0
- package/src/hosted/permissions.js +52 -6
- package/src/hosted/presence.js +31 -2
- package/src/hosted/projects.js +30 -2
- package/src/hosted/public.js +4 -4
- package/src/hosted/ratelimit.js +14 -0
- package/src/hosted/retention.js +18 -2
- package/src/hosted/server.js +123 -11
- package/src/hosted/shares.js +2 -2
- package/src/hosted/step-up-settings.js +68 -0
- package/src/hosted/step-up.js +135 -0
- package/src/hosted/tailnet-identity.js +24 -0
- package/src/hosted/tailnet-routes.js +342 -0
- package/src/hosted/tailnet.js +220 -0
- package/src/hosted/tailscale.js +75 -9
- package/src/hosted/tenancy.js +66 -1
- package/src/hosted/token-api.js +119 -20
- package/src/hosted/token-events.js +5 -3
- package/src/hosted/tokens.js +29 -6
- package/src/hosted/turn-hub.js +152 -0
- package/src/hosted/usage-core.js +624 -0
- package/src/hosted/usage-layout.js +724 -0
- package/src/hosted/usage-routes.js +375 -0
- package/src/hosted/usage-shape.js +256 -0
- package/src/hosted/usage.js +641 -0
- package/src/remote/agent-connect.js +469 -0
- package/src/remote/agent-fix.js +611 -0
- package/src/remote/agent-job.js +216 -0
- package/src/remote/agent-link.js +906 -0
- package/src/remote/agent-policy-file.js +242 -0
- package/src/remote/credentials.js +35 -1
- package/src/remote/login.js +44 -9
- package/src/remote/share.js +1 -1
- package/src/remote/tailnet-cli.js +547 -0
- package/src/server/app.js +15 -0
- package/src/server/pairing-routes.js +34 -5
- package/src/server/tailscale.js +97 -4
- package/src/tailnet-proof.js +766 -0
- package/dist/client/assets/BoardChat-DxehB761.js +0 -27
- package/dist/client/assets/ChecksPanel-pA_ueIaJ.js +0 -1
- package/dist/client/assets/History-C9N32kCv.js +0 -1
- package/dist/client/assets/LocalSettings-DawtKnvi.js +0 -1
- package/dist/client/assets/QuickConnect-DO1TjS1t.js +0 -1
- package/dist/client/assets/index-CsqLdqGx.css +0 -2
- package/dist/client/assets/index-DnZarJ3U.js +0 -37
- package/dist/client/assets/shield-check-QzwGhz0t.js +0 -1
- package/dist/client/assets/ui-DI-FGWWK.js +0 -41
- package/dist/console/assets/LocalAccountsApp-VOCZg8dg.js +0 -1
- package/dist/console/assets/LocalConsole-CMwAW-mF.js +0 -1
- package/dist/console/assets/app-update-dialog-Cw6UDqNP.js +0 -1
- package/dist/console/assets/console-DgfWmUEx.js +0 -55
- package/dist/console/assets/console-Lis0vvdL.css +0 -2
package/docs/hosted.md
CHANGED
|
@@ -25,20 +25,23 @@ SSRF surface. You capture on your machine or in CI (it can reach `localhost` and
|
|
|
25
25
|
shapewall hosted --data /var/lib/shapewall-hosted --origin https://app.example.com --port 4700 --trust-proxy
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
| Flag | Env
|
|
29
|
-
| ----------------------- |
|
|
30
|
-
| `--data DIR` | `SHAPEWALL_HOSTED_DATA`
|
|
31
|
-
| `--origin URL` | `SHAPEWALL_HOSTED_ORIGIN`
|
|
32
|
-
| `--port`/`--host` |
|
|
33
|
-
| `--signup` | `SHAPEWALL_HOSTED_SIGNUP`
|
|
34
|
-
| `--trust-proxy` | `SHAPEWALL_HOSTED_TRUST_PROXY=1`
|
|
35
|
-
| | `SHAPEWALL_HOSTED_SECRET`
|
|
36
|
-
| | `RESEND_API_KEY`
|
|
37
|
-
| | `SHAPEWALL_EMAIL_FROM`
|
|
38
|
-
| `--previous-origin URL` | `SHAPEWALL_HOSTED_PREVIOUS_ORIGIN`
|
|
39
|
-
| `--report-email ADDR` | `SHAPEWALL_HOSTED_REPORT_EMAIL`
|
|
40
|
-
|
|
|
41
|
-
|
|
|
28
|
+
| Flag | Env | Default | What |
|
|
29
|
+
| ----------------------- | ---------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
+
| `--data DIR` | `SHAPEWALL_HOSTED_DATA` | `./shapewall-hosted-data` | Database, secret, pushed files |
|
|
31
|
+
| `--origin URL` | `SHAPEWALL_HOSTED_ORIGIN` | `http://HOST:PORT` | The public origin. Passkeys are bound to its host name (the RP ID). |
|
|
32
|
+
| `--port`/`--host` | | `4700` on `127.0.0.1` | Keep it on loopback behind a reverse proxy |
|
|
33
|
+
| `--signup` | `SHAPEWALL_HOSTED_SIGNUP` | `invite` | `invite`: only invite links (and the setup link). `open`: anyone |
|
|
34
|
+
| `--trust-proxy` | `SHAPEWALL_HOSTED_TRUST_PROXY=1` | off | Client IPs from `X-Forwarded-For` (only from a proxy on this host) |
|
|
35
|
+
| | `SHAPEWALL_HOSTED_SECRET` | `<data>/secret.key` | Key for signed live-HTML URLs (made on first start, mode 0600) |
|
|
36
|
+
| | `RESEND_API_KEY` | unset | With `SHAPEWALL_EMAIL_FROM`: invite emails through Resend |
|
|
37
|
+
| | `SHAPEWALL_EMAIL_FROM` | unset | Sender for invite emails, e.g. `Shapewall <invites@example.com>` |
|
|
38
|
+
| `--previous-origin URL` | `SHAPEWALL_HOSTED_PREVIOUS_ORIGIN` | unset | The old origin during a move ([Moving to a new origin](#moving-to-a-new-origin)) |
|
|
39
|
+
| `--report-email ADDR` | `SHAPEWALL_HOSTED_REPORT_EMAIL` | unset | "Report this board" on public projects opens a mail to this address |
|
|
40
|
+
| `--tailnet-sign-in` | `SHAPEWALL_HOSTED_TAILNET_SIGN_IN=1` | off | With `--tailscale`: a tailnet user is signed in as the account linked to their tailnet login, no passkey ([Tailnet sign-in](#tailnet-sign-in)). Linux only |
|
|
41
|
+
| `--tailnet-passkeys` | `SHAPEWALL_HOSTED_TAILNET_PASSKEYS=1` | off | With `--tailnet-sign-in`: also allow passkeys ([With passkeys also allowed](#with-passkeys-also-allowed)); `hosted admin passkeys on\|off` wins over it |
|
|
42
|
+
| `--owners-see-sign-ins` | `SHAPEWALL_HOSTED_OWNERS_SEE_SIGN_INS=1` | off | Workspace owners see their members' sign-ins, passkey events and devices in Activity. For a server with one team ([Activity](#the-activity-page)) |
|
|
43
|
+
| | `SHAPEWALL_TURNSTILE_SITE_KEY` | unset | With `SHAPEWALL_TURNSTILE_SECRET`: a Cloudflare Turnstile check on open sign-up and comment share links |
|
|
44
|
+
| | `SHAPEWALL_TURNSTILE_SECRET` | unset | Turnstile secret key. Both keys or neither (one alone is a warning and stays off) |
|
|
42
45
|
|
|
43
46
|
It needs Node 22.13 or newer (it uses the built-in `node:sqlite`). Passkeys need a secure context: `https://`, or `http://localhost`
|
|
44
47
|
for trying it on your own machine (`--origin http://localhost:4700`; not `127.0.0.1`, which is not a valid passkey RP ID).
|
|
@@ -58,6 +61,554 @@ that origin to the console CSP. Off by default.
|
|
|
58
61
|
Deployment examples: [examples/hosted/shapewall-hosted.service](../examples/hosted/shapewall-hosted.service)
|
|
59
62
|
(systemd, hardened) and [examples/hosted/Caddyfile](../examples/hosted/Caddyfile).
|
|
60
63
|
|
|
64
|
+
## Signing in
|
|
65
|
+
|
|
66
|
+
Four ways to reach Shapewall, side by side. Pick by who has to reach the board.
|
|
67
|
+
|
|
68
|
+
| How you reach it | Command | How people sign in | Who can reach it |
|
|
69
|
+
| ----------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------ |
|
|
70
|
+
| Local board, on your machine | `shapewall serve` | Nothing: it is your board | This machine |
|
|
71
|
+
| Over an SSH tunnel | `ssh -L 4700:127.0.0.1:4700 server` | A local board: nothing, as if you sat at that machine. A hosted server: a passkey each | Whoever can SSH to the machine |
|
|
72
|
+
| Your tailnet, tailnet sign-in | `shapewall hosted --tailscale --tailnet-sign-in` | Your Tailscale account, from every tailnet device of yours. No passkey, no password. An admin invites | People on your tailnet |
|
|
73
|
+
| Your own domain | `shapewall hosted --origin https://app.example.com` | A passkey each | Anyone you invite |
|
|
74
|
+
|
|
75
|
+
A tailnet server can also run with passkeys instead of tailnet sign-in (`shapewall hosted --tailscale`: a passkey each), or
|
|
76
|
+
with both (`--tailnet-sign-in --tailnet-passkeys`). Everything after the sign-in is the same on every hosted server: accounts,
|
|
77
|
+
workspaces, roles, invites, the audit log.
|
|
78
|
+
|
|
79
|
+
### Over SSH
|
|
80
|
+
|
|
81
|
+
For people who do not use Tailscale: an SSH tunnel carries one port of the server's machine to your own.
|
|
82
|
+
|
|
83
|
+
```sh
|
|
84
|
+
# On the server (once): a hosted server for the address your browser will use. No TLS, no proxy, loopback only.
|
|
85
|
+
shapewall hosted --data ./hosted-data --port 4700 --origin http://shapewall.localhost:4700
|
|
86
|
+
|
|
87
|
+
# On your machine, each time:
|
|
88
|
+
ssh -L 4700:127.0.0.1:4700 you@server
|
|
89
|
+
# then open http://shapewall.localhost:4700
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
- **Give the tunnel a host name of its own: `shapewall.localhost`.** Browsers send every name that ends in `.localhost` to
|
|
93
|
+
your own machine and treat it as a secure context, so passkeys work without a certificate, and the name keeps the server's
|
|
94
|
+
cookies and passkeys to itself. Tested in Chromium (sign-up and sign-in with a passkey; the passkey belongs to
|
|
95
|
+
`shapewall.localhost`, the session cookie is sent to that name only).
|
|
96
|
+
- **Plain `http://localhost:4700` works too** (`--origin http://localhost:4700`), for a browser or a tool that does not
|
|
97
|
+
resolve `.localhost` names. Know what it means: **cookies are not kept apart by port.** At plain `localhost` the session
|
|
98
|
+
cookie is also sent to any other web server on your machine's `localhost` (a dev server on another port), and that server
|
|
99
|
+
could use it against Shapewall while you have the tunnel open. With `shapewall.localhost` it is not. Not `127.0.0.1`: not a
|
|
100
|
+
valid passkey host.
|
|
101
|
+
- **Accounts are passkey accounts** for that origin. The origin is part of the passkey: keep the same host name and the same
|
|
102
|
+
port on both ends. Everyone who tunnels in uses the same address and has their own account, role and passkey.
|
|
103
|
+
- **Everyone arrives from 127.0.0.1.** The server sees the SSH daemon's end of the tunnel, so all tunnelled people share one
|
|
104
|
+
address: the rate limits that count per address (sign-in attempts, recovery codes, invite lookups) are shared between
|
|
105
|
+
them, and the audit log and the device list show `127.0.0.1` for everyone. Who did what is still each person's account.
|
|
106
|
+
- **The first account** is made with the setup link, as on any server: `shapewall hosted setup-link --data ./hosted-data` on
|
|
107
|
+
the server prints `http://shapewall.localhost:4700/signup#setup=...`; open it through the tunnel.
|
|
108
|
+
- **The server listens on 127.0.0.1 only.** Nothing is open to the network; SSH is the way in, and whoever has an SSH login on
|
|
109
|
+
the machine can reach the port. Sign-in still decides who is who.
|
|
110
|
+
- **Share links** made there point at the tunnel's address too, so they work only for people with a tunnel. For links
|
|
111
|
+
anyone can open, use a tailnet with `--funnel` or your own domain.
|
|
112
|
+
- **A local board over a tunnel** (`shapewall serve --port 4600` on the remote machine, `ssh -L 4600:127.0.0.1:4600 ...`):
|
|
113
|
+
the board sees a connection from its own machine, so you are treated as the person sitting at it. There is no sign-in and no
|
|
114
|
+
pairing; comments, chat with the agent and approvals work as they do locally, and settings still need the private owner
|
|
115
|
+
link the terminal printed. That is right for your own machine over your own SSH login. It also means that every OS user on
|
|
116
|
+
that machine, and anyone you forward the port to, is that same person: do not tunnel a local board for other people; run
|
|
117
|
+
the hosted server for them.
|
|
118
|
+
|
|
119
|
+
Tested in the suite with the real command and a real browser at `http://shapewall.localhost:<port>` and at
|
|
120
|
+
`http://localhost:<port>` (sign-up, sign-out, sign-in with a passkey, and which of the two sends its session cookie to
|
|
121
|
+
another server on localhost; `test/e2e/hosted-ssh.e2e.test.js`). The tunnel itself is SSH's.
|
|
122
|
+
|
|
123
|
+
### When Shapewall asks for the passkey again
|
|
124
|
+
|
|
125
|
+
This section is about servers where passkeys are the sign-in. On a tailnet sign-in server without passkeys (the default
|
|
126
|
+
there) the fixed core below asks for a typed name instead, and nothing else asks: [Tailnet sign-in](#tailnet-sign-in).
|
|
127
|
+
|
|
128
|
+
Once you are signed in, your role decides what you may do, and that is all: approving an agent or a machine, agent settings,
|
|
129
|
+
tokens, share links, exports, an agent's edit and push cards, members and roles, deleting a project. No second prompt.
|
|
130
|
+
|
|
131
|
+
Two things ask for the passkey again ("Confirm it's you"):
|
|
132
|
+
|
|
133
|
+
**1. A small fixed core, always, on every server** (a passkey check in the last 10 minutes). These guard the account itself or
|
|
134
|
+
cannot be undone for everyone:
|
|
135
|
+
|
|
136
|
+
- adding or removing a passkey (`POST /auth/passkeys/options`, `POST /auth/passkeys/verify`, `DELETE /auth/passkeys/:id`);
|
|
137
|
+
- new recovery codes (`POST /auth/recovery-codes`);
|
|
138
|
+
- linking or unlinking a tailnet login (`POST` and `DELETE /auth/tailnet/link`; ticking the box at sign-up is the one way to
|
|
139
|
+
link without it);
|
|
140
|
+
- deleting your account (`DELETE /auth/me`);
|
|
141
|
+
- deleting a workspace (`DELETE /api/workspaces/:ws`);
|
|
142
|
+
- owners: making someone an owner, changing or removing an owner, inviting an owner (`PATCH` and `DELETE
|
|
143
|
+
/api/workspaces/:ws/members/:user`, `POST /api/workspaces/:ws/invites` with role `owner`);
|
|
144
|
+
- moving your sign-in to the server's new address (`POST /auth/rebind/start`);
|
|
145
|
+
- making the setting below weaker (`PATCH /api/workspaces/:ws/step-up`).
|
|
146
|
+
|
|
147
|
+
The list is one table in the code (`FIXED_CORE` in `src/hosted/step-up.js`), enforced in one place before any route runs.
|
|
148
|
+
"Sign out other devices" is not in it, but it is not free either: it needs a session that passed a passkey check at some
|
|
149
|
+
point (any passkey sign-in has), so a session someone merely holds cannot sign you out everywhere.
|
|
150
|
+
|
|
151
|
+
**2. What a workspace's owner switches on.** Settings, "Ask for a passkey again". Everything is off by default. One switch per
|
|
152
|
+
group:
|
|
153
|
+
|
|
154
|
+
| Group | Asks before |
|
|
155
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
156
|
+
| Agent edits and pushes | Allow on an agent's edit or command, Push this fix, approving an agent run or a shell command |
|
|
157
|
+
| Agents and machines | approving a machine or an agent (`shapewall login`, `agent connect`), who may use an agent, its approval rule, the project agent policy |
|
|
158
|
+
| Tokens and share links | new API tokens, new share links, turning share links or public projects on, making a project public |
|
|
159
|
+
| Members and roles | inviting an admin, making someone an admin, changing or removing an admin |
|
|
160
|
+
| Exports and deletes | exporting the workspace, deleting a project or a board |
|
|
161
|
+
|
|
162
|
+
With them: how long one check counts (5, 15, 30 or 60 minutes; 15 by default), and the admin idle rule (admin pages ask once more
|
|
163
|
+
after 12 hours without opening one). Only an owner changes these. Switching something on needs nothing more; switching it off or
|
|
164
|
+
choosing a longer time is part of the fixed core. Every change is in the audit log with the value before and after
|
|
165
|
+
(`step_up_changed`), and Activity's "Worth a look" filter marks it.
|
|
166
|
+
|
|
167
|
+
The server decides, route by route: it answers 403 `reauth_required` with a message that says which rule asked (and `stepUp` in the
|
|
168
|
+
error: `always`, the group's id, `adminIdle` or `restricted`), and only then does the console show the prompt. The console never
|
|
169
|
+
asks on its own.
|
|
170
|
+
|
|
171
|
+
A session that started with a recovery code, or with a passkey that was added with one in the last 24 hours, keeps the strict
|
|
172
|
+
rules whatever the workspace chose: everything in the groups above, and signing out other devices, needs a passkey check it cannot
|
|
173
|
+
give yet ([Accounts](#accounts)).
|
|
174
|
+
|
|
175
|
+
The audit log is unchanged: every action above is recorded as before, whether or not a passkey was asked for.
|
|
176
|
+
|
|
177
|
+
The settings as an API, one setting per request (owners): `PATCH /api/workspaces/:ws/step-up` with `{ "group": "tokens", "on":
|
|
178
|
+
true }`, `{ "windowMinutes": 30 }`, `{ "adminIdle": true }` or `{ "cliApproval": true }`. `GET /api/workspaces/:ws` carries them as
|
|
179
|
+
`workspace.settings.stepUp`.
|
|
180
|
+
|
|
181
|
+
### Tailnet sign-in
|
|
182
|
+
|
|
183
|
+
```sh
|
|
184
|
+
shapewall hosted --data ./hosted-data --tailscale --tailnet-sign-in # or SHAPEWALL_HOSTED_TAILNET_SIGN_IN=1
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
On your tailnet, your Tailscale account is the sign-in: one identity, your different machines, and they all reach the server
|
|
188
|
+
with no second credential. `tailscale serve` adds the identity of the person behind each request (`Tailscale-User-Login`,
|
|
189
|
+
`Tailscale-User-Name`), and the server signs that person in as the account linked to their login.
|
|
190
|
+
|
|
191
|
+
**No passkeys, by default.** On a server started with `--tailnet-sign-in` no passkey is asked for or offered: the sign-in page
|
|
192
|
+
shows "Continue as ada@example.com" (or the invited and not-invited states) and nothing else, the Account page has no passkeys
|
|
193
|
+
and no recovery codes, and every passkey route answers 403 `passkeys_off`. What that means, plainly:
|
|
194
|
+
|
|
195
|
+
- **The tailnet is the trust boundary.** Anything running as you on one of your tailnet devices can act as you on this
|
|
196
|
+
server: a script, a coding agent, a browser extension. Tailscale says which device a request came from and whose device it
|
|
197
|
+
is, not that you are at the keyboard. Lock your devices, and keep the tailnet to people and machines you trust.
|
|
198
|
+
- **The few things Shapewall always asks about ask you to type a name.** Deleting a workspace or your account, making,
|
|
199
|
+
changing or removing an owner (leaving as one too), inviting an owner: the console asks you to type the workspace's name
|
|
200
|
+
(your handle for the account), and the server refuses the request until it carries that name (403 `confirm_required`;
|
|
201
|
+
the header `X-Shapewall-Confirm`). On the command line the same things need `--yes`, and the command names what it
|
|
202
|
+
confirms. This is deliberateness, not proof: the identity is already proven, and a program acting as you can type too.
|
|
203
|
+
The header is no secret and no token: the request is refused from another site exactly as every other write is (the same
|
|
204
|
+
origin and JSON are required, and no other origin is allowed to send the header). When you are in more than one workspace
|
|
205
|
+
with the same name, the name would not say which, so the prompt asks for the workspace's id instead and shows it.
|
|
206
|
+
- **Nothing else asks.** A workspace's "Ask for a passkey again" switches have nothing to ask for; Settings shows
|
|
207
|
+
"Confirming changes" in their place.
|
|
208
|
+
- **Passkeys are an opt-in hardening.** Start the server with `--tailnet-passkeys` (or
|
|
209
|
+
`SHAPEWALL_HOSTED_TAILNET_PASSKEYS=1`), or switch them on a running server: `shapewall hosted admin passkeys on --data DIR`
|
|
210
|
+
(`off`, `status`; kept in the database, and it wins over the flag). Then anyone may add a passkey on the Account page, an
|
|
211
|
+
account that has one confirms the fixed core with it, and everything under
|
|
212
|
+
[With passkeys also allowed](#with-passkeys-also-allowed) applies. Switched off again, passkeys are kept and not used, and the switch does three things and says them: every session that a
|
|
213
|
+
passkey or a recovery code started is ended (deleted, so switching on later does not bring one back); a passkey that was
|
|
214
|
+
still on hold stays on hold, stays removable with "Not you? Remove it", and starts its 24 hours again when passkeys come
|
|
215
|
+
back; and each workspace that asks for a passkey somewhere ("Ask for a passkey again", the command line switch) gets an
|
|
216
|
+
audit entry and a line in Settings, "Switched on here, and not asked while this server has passkeys off": its settings are
|
|
217
|
+
kept and asked again when passkeys are. An account with no tailnet login cannot sign in until they are on again (the
|
|
218
|
+
command says how many). In this mode a tailnet session ends the account's other sessions with no further question.
|
|
219
|
+
|
|
220
|
+
**Each tailnet login is its own account, and an admin still decides who is in a workspace.** Being on the tailnet alone gives
|
|
221
|
+
nothing. Why:
|
|
222
|
+
|
|
223
|
+
- **Who did what.** Comments, approvals, the audit log and usage name a person. One shared identity for "the tailnet" would make
|
|
224
|
+
all of that anonymous.
|
|
225
|
+
- **Roles.** A viewer, a member, an admin and an owner are different things; agents have audiences. None of it works without
|
|
226
|
+
accounts.
|
|
227
|
+
- **A tailnet is wider than a team.** It holds family devices, a contractor's laptop, a build machine, nodes shared in from
|
|
228
|
+
someone else's tailnet. They can reach the server; that should not put them in your workspace.
|
|
229
|
+
|
|
230
|
+
How people get in:
|
|
231
|
+
|
|
232
|
+
- **The first owner** claims the server with the setup link, as on any server. Opened through the tailnet, the page offers
|
|
233
|
+
"Continue as ada@example.com" and links that login. From the command line:
|
|
234
|
+
`shapewall hosted claim --data DIR --login LOGIN` on the server's machine ([From your coding agent](#from-your-coding-agent)).
|
|
235
|
+
Opened from the server's own machine, the tailnet address links nothing: [why](#on-the-servers-own-machine).
|
|
236
|
+
- **Someone the server does not know** sees "Ask an admin of a workspace here to invite ada@example.com", and nothing else. The
|
|
237
|
+
admins of every workspace see them under Members, "Arrived through the tailnet", and can invite them with a role or take them
|
|
238
|
+
off the list (kept 30 days, at most 200).
|
|
239
|
+
- **An invite can be for one tailnet login** (Invite people, "Tailnet login"; `POST /invites` with `tailnetLogin`). Only that
|
|
240
|
+
login can use it, whoever has the link. They join the next time they open the server, with the role of the invite.
|
|
241
|
+
- **One login, one account.** (With passkeys allowed, an account that has a passkey links or unlinks its login on the
|
|
242
|
+
Account page; without them there is nothing to link or unlink.)
|
|
243
|
+
- **Tagged devices and nodes shared in without a user** carry no login. They are never signed in.
|
|
244
|
+
|
|
245
|
+
Good to know:
|
|
246
|
+
|
|
247
|
+
- **A tailnet session is bound to the identity.** It works only on requests that arrive as that login. Its cookie is worth
|
|
248
|
+
nothing off the tailnet, on another person's device, or through Funnel. It is marked "Signed in by tailnet" in the device list,
|
|
249
|
+
`via: tailnet` in the account's log, and `signedInBy: tailnet` on what it does in the workspace's audit log (Activity shows a
|
|
250
|
+
"tailnet" mark).
|
|
251
|
+
- **Signing out** keeps that browser signed out until you press "Continue as ada@example.com" on the sign-in page. Arriving again
|
|
252
|
+
would otherwise sign you straight back in; the page says so.
|
|
253
|
+
- **Share links, public boards and `--funnel`** work as on any server. The public listener never reads an identity.
|
|
254
|
+
|
|
255
|
+
### With passkeys also allowed
|
|
256
|
+
|
|
257
|
+
Only on a tailnet server where the operator switched passkeys on (`--tailnet-passkeys`, or `hosted admin passkeys on`). An
|
|
258
|
+
account may then add a passkey; one that has a passkey confirms the fixed core with it (a passkey check in the last 10
|
|
259
|
+
minutes) and no longer by typing a name, and a workspace's "Ask for a passkey again" switches work.
|
|
260
|
+
|
|
261
|
+
- **The fixed core without a passkey.** An account that only its tailnet signs in has no passkey to confirm with. For the few
|
|
262
|
+
things that always need one it is told to add a passkey first (403 `passkey_required`). Adding the first passkey needs no
|
|
263
|
+
passkey check (there is nothing stronger to check it against). What it does need, and what follows:
|
|
264
|
+
- **A browser and a named device.** The request must come from the Account page in a browser (not from the command line's
|
|
265
|
+
tailnet session, not from another site), and you confirm a step that names the device: "Add a passkey from Chrome on
|
|
266
|
+
Linux?". A program on your device can imitate both; they keep the command line and other sites out, and they put the
|
|
267
|
+
device's name on the passkey.
|
|
268
|
+
- **The passkey is on hold for 24 hours.** It signs in at once, and it cannot confirm the fixed core until the day is over,
|
|
269
|
+
exactly like a passkey added after a recovery code. It cannot add a second passkey or make recovery codes either.
|
|
270
|
+
- **Every page says so, on every device.** While it is on hold, each page of your account shows "A passkey was added from
|
|
271
|
+
Chrome on Linux" with the time, and **"Not you? Remove it"**. Any tailnet session of your account removes it with that
|
|
272
|
+
button: no passkey check (the only passkey there is to check with is the one in question), and it goes though it is your
|
|
273
|
+
only passkey and you have no recovery codes. The sessions that passkey signed in end, every other passkey still on hold
|
|
274
|
+
starts its 24 hours again, and the account is as it was before. Adding it is in the account's log and "Worth a look" in
|
|
275
|
+
Activity ("First passkey added in a tailnet session"); so is the removal.
|
|
276
|
+
- **After the 24 hours** it is an ordinary passkey: removing it needs a passkey check. If you find a passkey that is not
|
|
277
|
+
yours then, or cannot reach the server from a tailnet device, the server's operator removes it:
|
|
278
|
+
`shapewall hosted admin passkeys list|remove` ([Operator commands](#operator-commands-and-quotas)).
|
|
279
|
+
|
|
280
|
+
A tailnet identity is per device, so whatever runs as you on one of your devices could add a passkey of its own; the hold,
|
|
281
|
+
the notice and the removal are what stand between that and your account. So add your passkey before you need it, and look
|
|
282
|
+
at the notice when you did not. We chose this over "ask the proxy again": a second request through the proxy proves nothing
|
|
283
|
+
the first did not.
|
|
284
|
+
|
|
285
|
+
- **Ending your other sessions** ("Sign out other devices") needs a session that passed a passkey check at some point, or an
|
|
286
|
+
account with no passkey at all. A tailnet session of an account that has a passkey confirms with it once.
|
|
287
|
+
- **Signing up with a passkey while you arrive through the tailnet does not link your login.** The sign-up page has a box,
|
|
288
|
+
"Also sign me in from this tailnet login", off by default. Ticked, the link is in the account's log (`tailnet_linked`).
|
|
289
|
+
- **`shapewall login` and `agent connect`** are approved in the browser by a tailnet-signed-in admin with no passkey, or with no
|
|
290
|
+
browser at all ([From your coding agent](#from-your-coding-agent)), unless the workspace switched on "Approve command line
|
|
291
|
+
logins in the browser": then the server takes an approval only from a session with a passkey check in the last 10 minutes,
|
|
292
|
+
whatever the client is and whatever it sends. The same switch keeps a session that only a tailnet identity stands behind
|
|
293
|
+
from making an API token and from inviting or making an admin (an admin could do the first two); it covers those three
|
|
294
|
+
things and nothing else that session's role allows.
|
|
295
|
+
- **People from another tailnet who accepted a share of this machine** do carry a login (Tailscale sets the headers for them).
|
|
296
|
+
They are visitors like anyone else: listed for the admins, in nothing until invited.
|
|
297
|
+
|
|
298
|
+
### How the server knows a request came through tailscale serve
|
|
299
|
+
|
|
300
|
+
The identity headers are only as good as the path they came by. `tailscale serve` removes any `Tailscale-User-*` header a client
|
|
301
|
+
sent and sets its own, for traffic from tailnet users only: none for tagged devices, none for Funnel
|
|
302
|
+
([Tailscale: identity headers](https://tailscale.com/kb/1312/serve#identity-headers)). But the server listens on `127.0.0.1`, and
|
|
303
|
+
other things can open that port and write the same headers:
|
|
304
|
+
|
|
305
|
+
- any program on the machine, directly;
|
|
306
|
+
- any program on the machine, through tailscaled: it asks for the server's own tailnet address
|
|
307
|
+
(`https://board.example.ts.net/`), and serve answers its own machine like any other device, with the machine owner's login;
|
|
308
|
+
- a tailnet device, when tailscaled runs in userspace-networking mode: its netstack forwards a raw TCP connection to the
|
|
309
|
+
machine's tailnet address, on a port serve does not handle, to `127.0.0.1:<same port>`, and tailscaled itself dials it;
|
|
310
|
+
- a local user through tailscaled's own dialler (`tailscale nc`, before Tailscale 1.98), or through tailscaled's SOCKS5 or
|
|
311
|
+
outbound HTTP proxy.
|
|
312
|
+
|
|
313
|
+
The last three arrive from a socket that tailscaled owns. So no single check is proof, and an identity is believed only when
|
|
314
|
+
**all** of these hold:
|
|
315
|
+
|
|
316
|
+
1. **The secret.** At each start the server makes a random secret and points its serve entry at
|
|
317
|
+
`http://127.0.0.1:<port>/_ts/<secret>`. Serve puts the path of its target in front of every request it proxies; a raw
|
|
318
|
+
forward, a dial or a proxy passes the client's own path. A request without the secret is never asked who it is. This stops a
|
|
319
|
+
tailnet device, and anything else that cannot read this machine's serve config. **It does not stop a local user:** any local
|
|
320
|
+
user can read the serve config (`tailscale serve status` works for a user who is not the Tailscale operator; checked), secret
|
|
321
|
+
included. The secret is in no log line, error or response; a wrong one gets a plain 404.
|
|
322
|
+
2. **The peer.** The connection's other end must be a socket owned by root, the user tailscaled runs as. On Linux the kernel
|
|
323
|
+
lists every TCP socket with its owner in `/proc/net/tcp`, and the server looks the peer up for each connection. This stops
|
|
324
|
+
a local program that connects to the port itself, though it has the secret: its socket is its own. It does not stop a local
|
|
325
|
+
program that asks tailscaled for the serve address (check 4 does). There is no setting to name another user.
|
|
326
|
+
3. **tailscaled vouches.** For each request the server asks tailscaled who owns the address in `X-Forwarded-For` (which serve
|
|
327
|
+
sets to the tailnet address the request came from): `tailscale whois`. It must be a user's device, not tagged, with a key
|
|
328
|
+
that has not expired, of the same login as the header, and the answer must name the user by Tailscale's id. Kept for a minute per connection and address. Not proof alone (the address is a header too), required
|
|
329
|
+
in addition.
|
|
330
|
+
4. **Not this machine.** A request whose source is the server's own machine is never taken by its tailnet identity. Any
|
|
331
|
+
program there, under any user, can ask tailscaled for the serve address; serve then sets the machine owner's login, adds the
|
|
332
|
+
secret and dials the server from a root socket, and whois agrees. Nothing in such a request says which local user or
|
|
333
|
+
program made it. So the server refuses when the address in `X-Forwarded-For` is one of this node's own tailnet addresses
|
|
334
|
+
(IPv4 or IPv6, from `tailscale status --json`, read again every 30 seconds), or when whois says the address belongs to this
|
|
335
|
+
node (compared by the node's stable id, not by a name). The machine's network interfaces are read on every request as
|
|
336
|
+
well, so an address tailscaled was given a moment ago counts at once. If the server cannot tell which node it is, nobody
|
|
337
|
+
is believed.
|
|
338
|
+
What this means for the owner: [On the server's own machine](#on-the-servers-own-machine).
|
|
339
|
+
5. **The headers are clean.** Exactly one `Tailscale-User-Login`, no `Tailscale-Funnel-Request`, a value that is plain ASCII or
|
|
340
|
+
RFC 2047 encoded UTF-8 (what Tailscale sends for non-ASCII names) and reads as `user@domain`. Twice, empty, another
|
|
341
|
+
character set, a broken escape: nobody.
|
|
342
|
+
6. **The request is from this origin.** The proxy adds the identity to every request a device makes, also one that a page on
|
|
343
|
+
another site made the browser send. So the identity alone only answers `GET /auth/me` with `Sec-Fetch-Site: same-origin`
|
|
344
|
+
and the `POST /auth/tailnet/*` routes (same-origin and JSON, as for every write). Everything else needs the session cookie
|
|
345
|
+
as before. `GET /auth/me` never makes a session: for a linked login it answers `"tailnet":{"state":"linked"}`, and the
|
|
346
|
+
console and the command line then sign in with `POST /auth/tailnet/sign-in` (rate limited per login). An account keeps at
|
|
347
|
+
most 20 tailnet sessions per login; signing in again past that ends the oldest.
|
|
348
|
+
|
|
349
|
+
**The feature refuses to turn on, and the server does not start,** when the peer check would not mean what it must. While the
|
|
350
|
+
server runs the same is checked every 30 seconds, and nobody is signed in by tailnet identity until it is right again (tailnet
|
|
351
|
+
sessions stop counting and their open live streams are cut; passkey sessions go on; the log says why):
|
|
352
|
+
|
|
353
|
+
- not Linux (macOS and Windows have no such table), `/proc/net/tcp` unreadable, or a test connection from the server itself not
|
|
354
|
+
recognised;
|
|
355
|
+
- tailscaled in **userspace-networking mode** (`tailscale status --json` says `TUN: false`, or it was started with
|
|
356
|
+
`--tun=userspace-networking`);
|
|
357
|
+
- **Tailscale older than 1.98**;
|
|
358
|
+
- tailscaled running a **SOCKS5 or outbound HTTP proxy** (`--socks5-server`, `--outbound-http-proxy-listen`, read from its
|
|
359
|
+
command line in `/proc`);
|
|
360
|
+
- no tailscaled of root found, more than one, or its command line not readable. Which process is tailscaled: where systemd
|
|
361
|
+
runs it, the main process of `tailscaled.service` (`systemctl show -p MainPID`) and no other, whatever else on the machine
|
|
362
|
+
is called `tailscaled`; without systemd, a process named `tailscaled` (where `/proc/<pid>/exe` can be read, the program
|
|
363
|
+
file itself must be). In both cases only a process that is root in all four of its ids (the `Uid:` line of
|
|
364
|
+
`/proc/<pid>/status`): a setuid-root program that an ordinary user started under that name is ignored, cannot be mistaken
|
|
365
|
+
for the daemon, and cannot switch the feature off;
|
|
366
|
+
- tailscaled started with `TS_DEBUG_NETSTACK_LOOPBACK_PORT` or `TS_DEBUG_NETSTACK_SUBNETS` in its environment (debugging
|
|
367
|
+
switches that make tailscaled forward tailnet connections to loopback), when the server can read that environment;
|
|
368
|
+
- the server cannot tell which node it is (`tailscale status --json` without `Self.ID` or without its tailnet addresses);
|
|
369
|
+
- the server in a **container or a user namespace**, where "root" may not be the machine's root (a `/.dockerenv` or
|
|
370
|
+
`/run/.containerenv` file, a container cgroup, `container` or `KUBERNETES_SERVICE_HOST` in the environment, or a uid map
|
|
371
|
+
that is not the machine's own);
|
|
372
|
+
- the serve config not the one entry the server added: a raw TCP forward to its port (under any spelling of loopback), another
|
|
373
|
+
serve entry to it, Funnel on its port, or its own entry gone or changed.
|
|
374
|
+
|
|
375
|
+
Run with passkeys in those cases (`--tailscale` without `--tailnet-sign-in`).
|
|
376
|
+
|
|
377
|
+
**What is still trusted.** Root on the server's machine, and whoever may change tailscaled's serve config there (the Tailscale
|
|
378
|
+
operator). Either can pretend to be anyone. Nothing else on the machine is trusted, and nothing on the tailnet. tailscaled's
|
|
379
|
+
environment is part of that root configuration: `/proc/<pid>/environ` of a root process is readable only by root, so a server
|
|
380
|
+
that runs as an ordinary user (as it should) cannot see the two debugging switches above and trusts root not to have set them.
|
|
381
|
+
|
|
382
|
+
### On the server's own machine
|
|
383
|
+
|
|
384
|
+
The server's own machine is never signed in by its tailnet identity, in the browser or from the command line: a request from
|
|
385
|
+
there proves only that something on the machine made it. What to use there instead:
|
|
386
|
+
|
|
387
|
+
- **Hosted server: two ways.**
|
|
388
|
+
1. **Another tailnet device of yours.** Your phone or laptop opens the server and is you. The sign-in page on the server's
|
|
389
|
+
machine says so: "This is the server's own machine: the server never takes a tailnet identity from here".
|
|
390
|
+
2. **The operator's commands on the machine, with the data folder.** Being able to read and write the data folder is the
|
|
391
|
+
proof, as for `hosted claim`. They cover what an owner needs there:
|
|
392
|
+
|
|
393
|
+
```sh
|
|
394
|
+
shapewall hosted claim --data ./hosted-data --login ada@example.com # the first account
|
|
395
|
+
shapewall hosted admin members list --data ./hosted-data
|
|
396
|
+
shapewall hosted admin members add --login ben@example.com --role admin --data ./hosted-data
|
|
397
|
+
shapewall hosted admin members remove --handle ben --data ./hosted-data
|
|
398
|
+
shapewall hosted admin members relink --handle ben [--login ben@new.example] --data ./hosted-data
|
|
399
|
+
shapewall hosted admin members unlink --handle ben --data ./hosted-data
|
|
400
|
+
shapewall hosted admin invites list|create --login cyd@example.com|revoke ID --data ./hosted-data
|
|
401
|
+
shapewall hosted admin projects list --data ./hosted-data
|
|
402
|
+
shapewall hosted admin passkeys status|on|off --data ./hosted-data
|
|
403
|
+
shapewall hosted admin passkeys list|remove ID --login ada@example.com --data ./hosted-data
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
`members add` puts an existing account in at once (or changes its role); a tailnet login with no account yet gets an
|
|
407
|
+
invite that only that login can take. `members remove` also revokes the invites, share links and API tokens that person made. With
|
|
408
|
+
several workspaces add `--workspace ID`. Every one of these is in the operator log and in the workspace's audit log as
|
|
409
|
+
"Server operator".
|
|
410
|
+
|
|
411
|
+
`shapewall login` and `shapewall agent connect` on the server's machine fall back to the code (approve it in a browser on
|
|
412
|
+
another device); `shapewall join` and `shapewall admin` say to run them on another tailnet device. Where passkeys are
|
|
413
|
+
allowed, a passkey session works from the machine as from anywhere.
|
|
414
|
+
|
|
415
|
+
- **Local board** (`shapewall serve --tailscale`). On the machine itself open `http://localhost:<port>`: the board's own
|
|
416
|
+
machine is the owner there by the settings token, as without Tailscale. The tailnet address opened from the machine itself
|
|
417
|
+
asks to pair, and the pairing page says why. On a local board a peer check that fails its self test at start keeps
|
|
418
|
+
identity off until the board is started again; the 30 second watch never switches it back on.
|
|
419
|
+
|
|
420
|
+
One consequence to know: an owner who works only on the server's machine and has no second tailnet device cannot open the
|
|
421
|
+
console of a tailnet sign-in server from there. The operator's commands above are for that; for the console itself, use a
|
|
422
|
+
second device, or run the server with passkeys and reach it [over SSH](#over-ssh) instead.
|
|
423
|
+
|
|
424
|
+
**An identity is per device, not per person.** Tailscale says which device a request came from and whose device it is. It
|
|
425
|
+
cannot say that the person is at the keyboard. Anything running as you on a tailnet device of yours (a script, a coding agent,
|
|
426
|
+
a browser extension, malware) can act as you here, as far as a tailnet session goes. That is why the fixed core asks for a
|
|
427
|
+
passkey, why a first passkey is on hold for a day, and why a workspace can require a passkey for approving machines and for making
|
|
428
|
+
tokens ("Approve command line logins in the browser": with it on, a session that only a tailnet identity stands behind can
|
|
429
|
+
neither approve a command line login nor make an API token on a project's page; alone, the first would be no barrier, since
|
|
430
|
+
a token is what a command line works with). If that is not acceptable for your team, use passkeys.
|
|
431
|
+
|
|
432
|
+
**An account is held to the tailnet user, not to the login's spelling.** A login is a name (`ada@example.com`), and a name can
|
|
433
|
+
be given to someone else later, or a node shared in from another tailnet can carry one that reads the same. So when a login is
|
|
434
|
+
linked the server keeps Tailscale's own id of the user (from `tailscale whois`, `UserProfile.ID`), and every later request must
|
|
435
|
+
carry the same id: a request with the right login and another id is nobody ("This tailnet login belongs to someone else here"),
|
|
436
|
+
and so is a whois answer with no user id at all. If that happens to your own account (Tailscale gave you a new user id:
|
|
437
|
+
the tailnet moved to another identity provider, or you were removed and added again), the page shows the command for
|
|
438
|
+
whoever runs the server: `shapewall hosted admin members relink --login you@example.com --data DIR` forgets the stored id,
|
|
439
|
+
so the next arrival as that login is taken as the account's person. `members relink --handle HANDLE --login NEW` links the
|
|
440
|
+
account to another login, and `members unlink --handle HANDLE` takes the login off. The operator decides because nobody
|
|
441
|
+
in the product can tell a new id for the same person from the same name given to someone else; each is in the operator log
|
|
442
|
+
and in the account's own log. A link made by `hosted claim --login` knows only the name: it takes the id of
|
|
443
|
+
the first proven request that arrives as that login, so open the server from your own device soon after claiming. A device
|
|
444
|
+
whose key has expired is nobody.
|
|
445
|
+
|
|
446
|
+
**"Root on this machine" is what the peer check proves, and no more.** It shows that the connection was opened by a process of
|
|
447
|
+
this machine's root. That this process is tailscaled's serve proxy follows from the other checks (the secret, the refusal
|
|
448
|
+
list below it, the serve config). And Tailscale's identity is the device's: **several OS users of one tailnet device all count
|
|
449
|
+
as that device's owner**. A family computer signed in to Tailscale as Ada signs every one of its users in as Ada. Tailscale's
|
|
450
|
+
serve documentation does not spell this out; it follows from how the identity headers are made (from the connection's source
|
|
451
|
+
device).
|
|
452
|
+
|
|
453
|
+
### What was and was not checked against real Tailscale
|
|
454
|
+
|
|
455
|
+
Checked on a real machine (Tailscale 1.104.2, Linux), read-only:
|
|
456
|
+
|
|
457
|
+
- `tailscaled` runs as root, and its command line is readable in `/proc` by an ordinary user;
|
|
458
|
+
- `tailscale status --json` has `TUN` (true there) and `Version` ("1.104.2-...");
|
|
459
|
+
- `tailscale serve status --json` has the shape the server reads for an HTTPS entry (`TCP`, `Web`, `Handlers`, `Proxy`), and
|
|
460
|
+
**a user who is not the operator can read it** (run as `nobody`): the secret is not secret from local users;
|
|
461
|
+
- `tailscale whois --json <address>` answers `Node` and `UserProfile.LoginName` for this machine's own tailnet address, and
|
|
462
|
+
"peer not found" for an address that is nobody's;
|
|
463
|
+
- `tailscale status --json` has `Self.ID` and `Self.TailscaleIPs` (IPv4 and IPv6), and whois on one of those addresses
|
|
464
|
+
answers `Node.StableID` equal to `Self.ID`;
|
|
465
|
+
- one capture of real requests through an existing serve entry, made from the machine itself: the request arrived from a
|
|
466
|
+
root-owned socket, with the entry's path in front, the identity headers set to the machine owner's login, and exactly one
|
|
467
|
+
`X-Forwarded-For` holding one of the machine's own tailnet addresses. That is the request check 4 refuses;
|
|
468
|
+
- the `/proc/net/tcp` lookup names the right owner for a real loopback connection (a test in the suite, on Linux).
|
|
469
|
+
|
|
470
|
+
**Run against a real tailscaled** (Tailscale 1.102.5, Linux, kernel mode, other serve entries on the machine, and a second
|
|
471
|
+
tailnet device), with a build of this release from before the last review round:
|
|
472
|
+
|
|
473
|
+
- the serve entry with the `/_ts/<secret>` target was accepted, and requests arrived with the secret path in front;
|
|
474
|
+
- a visitor from the other device was recognised by login, over IPv4 and IPv6, with the real whois;
|
|
475
|
+
- forged `Tailscale-User-Login`, `Tailscale_User_Login` and `X-Forwarded-For` headers sent by that visitor were ignored;
|
|
476
|
+
- a guessed secret path got 404, and the server's local port was not reachable from the tailnet;
|
|
477
|
+
- the server's own machine got "This is the server's own machine" by the server's name, by its own IPv4 and by its IPv6;
|
|
478
|
+
- a direct loopback request with a forged header was nobody, without the secret and with the real one;
|
|
479
|
+
- `hosted claim --login`, then from the other device `admin projects create` and `list`, `admin members list`, `admin agents
|
|
480
|
+
list` and `login --project` with no code; `admin` from the server's own machine was refused with its message;
|
|
481
|
+
- stopping the server removed its serve entry, and Tailscale 1.94 was refused at start with its message.
|
|
482
|
+
|
|
483
|
+
That run was made before four things in this release existed, so they are covered by the suite's stand-in only: holding an
|
|
484
|
+
account to Tailscale's id of the user (`UserProfile.ID` in whois), finding tailscaled by its systemd unit, reading the
|
|
485
|
+
machine's network interfaces on every request, and the server without passkeys (typed confirmation, the operator's
|
|
486
|
+
commands).
|
|
487
|
+
|
|
488
|
+
Read in Tailscale's source (`ipn/ipnlocal/serve.go`, `wgengine/netstack`, `cmd/tailscaled`), not run: that the userspace
|
|
489
|
+
netstack forwards raw TCP to loopback; the proxy flags; the debug switches.
|
|
490
|
+
|
|
491
|
+
**Not checked against a live serve:**
|
|
492
|
+
|
|
493
|
+
- **a tagged device** (how `tailscale whois --json` marks it on your version; the code reads `Node.Tags`), and a device
|
|
494
|
+
shared in from another tailnet;
|
|
495
|
+
- **the suspension within 30 seconds** when the serve config changes under a running server (a raw TCP forward, Funnel, the
|
|
496
|
+
entry changed), and that sign-in comes back when it is put right;
|
|
497
|
+
- **a sign-in in a real browser** through the tailnet (the browser tests send the headers themselves);
|
|
498
|
+
- and, smaller: whether the server can read `/proc/<pid>/environ` of tailscaled anywhere it is meant to run (as an ordinary
|
|
499
|
+
user it cannot), and the time `tailscale whois` takes per new connection under load.
|
|
500
|
+
|
|
501
|
+
[Checking it on your own tailnet](#checking-it-on-your-own-tailnet) below goes through all of it, these three included.
|
|
502
|
+
|
|
503
|
+
### Checking it on your own tailnet
|
|
504
|
+
|
|
505
|
+
The tests run without a tailnet, against a stand-in for `tailscale serve`. Before you rely on tailnet sign-in, check it on
|
|
506
|
+
yours. You need the server's machine, a second tailnet device of your own, and if you can a tagged device and a device of
|
|
507
|
+
another person. Nothing here changes any setting except starting the server.
|
|
508
|
+
|
|
509
|
+
1. **Start it and read what it says.** `shapewall hosted --data ./hosted-data --tailscale --tailnet-sign-in`. It either prints
|
|
510
|
+
the private address or refuses and says why ([the list](#how-the-server-knows-a-request-came-through-tailscale-serve)).
|
|
511
|
+
A refusal is the feature working: run with passkeys there.
|
|
512
|
+
2. **The serve entry.** `tailscale serve status --json` on the server's machine shows one HTTPS entry whose `Proxy` is
|
|
513
|
+
`http://127.0.0.1:<port>/_ts/<a long secret>`, no `TCP` forward to that port and no Funnel.
|
|
514
|
+
3. **Claim, from the server's machine:** `shapewall hosted claim --data ./hosted-data --login <your tailnet login>`. It prints
|
|
515
|
+
the owner account and the login it linked.
|
|
516
|
+
4. **From your second device, open the address.** You are signed in as that account with no passkey. Account, "Devices"
|
|
517
|
+
shows a session marked tailnet. This is the one check that needs a real request from another device; the suite cannot
|
|
518
|
+
make it.
|
|
519
|
+
5. **From the server's own machine, open the same address.** You must not be signed in: the page says "This is the server's
|
|
520
|
+
own machine". `curl -s https://<name>.ts.net/auth/me -H 'Sec-Fetch-Site: same-origin'` there answers
|
|
521
|
+
`"tailnet":{"state":"self"}`. If it signs you in, stop and report it.
|
|
522
|
+
6. **Forge it.** On the server's machine: `curl -s http://127.0.0.1:<port>/auth/me -H 'Tailscale-User-Login: <your login>'
|
|
523
|
+
-H 'Sec-Fetch-Site: same-origin'` must answer `"user":null` and never `"state":"linked"` (a `GET` makes no session anywhere; `linked` would mean the forged login was believed), and so must the same request with the `/_ts/<secret>` path
|
|
524
|
+
from the serve config in front and `-H 'X-Forwarded-For: <your second device's tailnet address>'`. The server log has
|
|
525
|
+
"ignored identity headers" with the check that failed (the connection did not come from tailscaled).
|
|
526
|
+
7. **A tagged device, and another person's device,** if you have them: the first sees "Your tailnet did not say who you
|
|
527
|
+
are", the second "Ask an admin of a workspace here to invite ..." and appears under Members, "Arrived through the
|
|
528
|
+
tailnet". Neither is in anything.
|
|
529
|
+
8. **The first passkey, if you allowed passkeys** (`shapewall hosted admin passkeys on`; without it the Account page has no
|
|
530
|
+
passkeys and step 8 does not apply). On the second device add a passkey on the Account page: it asks you to confirm the device by name,
|
|
531
|
+
then every page shows "A passkey was added from ...". Press "Not you? Remove it" from a third device or the same one: it
|
|
532
|
+
is gone, with no passkey prompt. `shapewall hosted admin passkeys list --login <your login> --data ./hosted-data` on the
|
|
533
|
+
server shows the same.
|
|
534
|
+
9. **Break it and watch it stop.** `tailscale serve --tcp=<port> tcp://127.0.0.1:<port>` on the server's machine (a raw
|
|
535
|
+
forward to the server's port); within 30 seconds the log says tailnet sign-in is suspended and the second device is
|
|
536
|
+
signed out. Remove the forward (`tailscale serve --tcp=<port> off`): sign-in comes back. Do this only on a machine whose
|
|
537
|
+
serve config is yours to change.
|
|
538
|
+
10. **Which tailscaled.** `systemctl show -p MainPID --value tailscaled.service` is the process the server checks; its
|
|
539
|
+
`Uid:` line in `/proc/<pid>/status` is `0 0 0 0`. Without systemd the server goes by the process name.
|
|
540
|
+
|
|
541
|
+
What to send us if a step fails: the Tailscale version, the step, and the "ignored identity headers" line. Not the serve
|
|
542
|
+
config: it holds the secret.
|
|
543
|
+
|
|
544
|
+
### From your coding agent
|
|
545
|
+
|
|
546
|
+
On a server with tailnet sign-in, an agent or a terminal on a tailnet machine is already known to the server as that machine's
|
|
547
|
+
tailnet user. Nothing below needs a browser unless it says so. Each command asks the server who it is (through `tailscale
|
|
548
|
+
serve`, by the same rule as the browser), gets a session that works only with that identity, uses the console's own API with it
|
|
549
|
+
(the same role checks, the same audit entries, marked as a tailnet session from "Shapewall CLI"), and signs out when it ends.
|
|
550
|
+
No admin token is stored anywhere.
|
|
551
|
+
|
|
552
|
+
**1. An owner sets up a server and a first project.** On the machine that runs the server:
|
|
553
|
+
|
|
554
|
+
```sh
|
|
555
|
+
shapewall hosted --data ./hosted-data --tailscale --tailnet-sign-in & # needs Tailscale, MagicDNS and HTTPS certificates
|
|
556
|
+
shapewall hosted claim --data ./hosted-data --login ada@example.com --workspace-name "Team" # no browser
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
Then on another tailnet device of the owner's (the server's own machine is never signed in by its tailnet identity:
|
|
560
|
+
[why](#on-the-servers-own-machine)):
|
|
561
|
+
|
|
562
|
+
```sh
|
|
563
|
+
shapewall admin projects create "My site" --remote https://board.example.ts.net
|
|
564
|
+
shapewall login --remote https://board.example.ts.net # no code, no browser: a token for the project
|
|
565
|
+
shapewall push --remote https://board.example.ts.net
|
|
566
|
+
shapewall admin invites create --login ben@example.com --role admin --remote https://board.example.ts.net
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
`hosted claim` reads the one-time setup link from the data folder: being able to read that folder is the proof, as it is for
|
|
570
|
+
`hosted setup-link`. It does not ask the tailnet who you are, because on the server's own machine the tailnet cannot say.
|
|
571
|
+
`--login` names the owner's tailnet login and is required; it must read as a login (`ada@example.com`), it is taken on your
|
|
572
|
+
word, and the command prints what it linked: the server's address, the owner account and its handle, the tailnet login, the
|
|
573
|
+
workspace. A server is claimed once: with an account already there, or the setup link used or replaced, the command refuses.
|
|
574
|
+
The audit log records the account and the link as made by "hosted claim on the server". From another tailnet device, with the
|
|
575
|
+
setup link in hand, `shapewall hosted claim --setup-link URL` asks the server who is asking instead, and `--login` there only
|
|
576
|
+
refuses anyone else. No passkey is made and none is needed: the Tailscale account is the sign-in. The few things Shapewall
|
|
577
|
+
always asks about need `--yes` on the command line (`shapewall admin invites create --role owner --yes`), which names what
|
|
578
|
+
it confirms. Where the operator allowed passkeys, an account that has one confirms those in the browser instead.
|
|
579
|
+
|
|
580
|
+
**2. A member joins and connects their machine.** On their own tailnet machine, after an admin invited their login:
|
|
581
|
+
|
|
582
|
+
```sh
|
|
583
|
+
shapewall join --remote https://board.example.ts.net # takes the invite made for your login
|
|
584
|
+
shapewall agent connect --remote https://board.example.ts.net --project my-site --name "Builder"
|
|
585
|
+
```
|
|
586
|
+
|
|
587
|
+
`join` reports the workspace, your role and its projects. With an invite link instead: `shapewall join --remote URL --invite
|
|
588
|
+
LINK`. The role is always the invite's; there is no way to choose one, and no way into a workspace that did not invite you.
|
|
589
|
+
`agent connect` (and `shapewall login`) is approved by your own tailnet identity when your role may make tokens (admin or owner),
|
|
590
|
+
with the scopes the browser's approval page gives; the audit entry says "approved by tailnet identity" with the machine's name.
|
|
591
|
+
A member or viewer gets the usual code, for an admin to approve in the browser. **Needs a browser:** nothing, for an admin.
|
|
592
|
+
|
|
593
|
+
The rules of those commands:
|
|
594
|
+
|
|
595
|
+
- **Which project.** `--project <slug>` (and `--workspace <name>` when you are in several). With one project it is picked.
|
|
596
|
+
Otherwise the command lists the projects with the exact flags to add and exits with an error. It never prompts.
|
|
597
|
+
- **An agent's look and audience** come from flags: `--name`, `--icon`, `--tint`, `--used-by owner|trusted` (default `owner`:
|
|
598
|
+
only you). Named members are picked in the console.
|
|
599
|
+
- **A workspace can require the browser and a passkey:** Settings, "Approve command line logins in the browser" (owners). The
|
|
600
|
+
server then refuses an approval from any session that only a tailnet identity stands behind (no passkey check in the last 10
|
|
601
|
+
minutes): `login` and `agent connect` show the code, and whoever approves it confirms with a passkey. Such a session can
|
|
602
|
+
then not make an API token or invite or make an admin either (`shapewall admin invites create --role admin` says so). This is decided by the
|
|
603
|
+
server from the session; nothing the command line or a browser sends changes it. A workspace that asks for a passkey for
|
|
604
|
+
"Agents and machines" gets the code too.
|
|
605
|
+
- **When it does not apply** (the server has no tailnet sign-in, the request did not come through the tailnet, a tagged device, a
|
|
606
|
+
login with no account): `login` and `agent connect` use the code and the browser, unchanged. `join` says that an account
|
|
607
|
+
needs a passkey, which is made in the browser, and gives the link. `admin` says it would need an admin token, which does not
|
|
608
|
+
exist yet, and points at the console.
|
|
609
|
+
- **The admin commands** are these and no more: `admin projects list|create NAME`, `admin invites create --login LOGIN | --link
|
|
610
|
+
[--role ROLE] [--days N]`, `admin members list`, `admin agents list` (`--json` for scripts).
|
|
611
|
+
|
|
61
612
|
## Accounts
|
|
62
613
|
|
|
63
614
|
- **Passkeys only.** No email, no passwords. Sign-up and sign-in use discoverable credentials with user verification required, so
|
|
@@ -70,7 +621,7 @@ Deployment examples: [examples/hosted/shapewall-hosted.service](../examples/host
|
|
|
70
621
|
has not used before is marked "Signed in on a new device" in Account activity.
|
|
71
622
|
- **Recovery codes.** Ten one-time codes (about 128 bits each), stored as SHA-256 hashes, shown once. A code plus your handle signs you
|
|
72
623
|
in and ends every other session of the account (a stolen device loses its session). That session is never "fresh": in its first 30
|
|
73
|
-
minutes it can add a passkey, and nothing
|
|
624
|
+
minutes it can add a passkey, and nothing that ever asked for a passkey check. A passkey added that way signs in, but is on hold for 24 hours before it can
|
|
74
625
|
confirm sensitive actions, so someone with one stolen code cannot lock the owner out: the owner's own passkey still removes theirs
|
|
75
626
|
(which ends their sessions) and makes new codes. Making new codes voids the old ones. Lose every passkey and every code and the
|
|
76
627
|
account is gone, but its work is not: projects belong to workspaces, so an admin removes the old member and invites the new account.
|
|
@@ -79,19 +630,19 @@ Deployment examples: [examples/hosted/shapewall-hosted.service](../examples/host
|
|
|
79
630
|
90 days at most. Signing in replaces the browser's previous session. The Account page lists your signed-in devices (browser and OS
|
|
80
631
|
from the user agent, IP, last used); sign one out, or "Sign out other devices" for all of them. Removing a passkey also ends the
|
|
81
632
|
other sessions. The list carries a session id, never the cookie or its hash.
|
|
82
|
-
- **
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
633
|
+
- **Asking for the passkey again.** By default a signed-in session with the right role is enough. A small fixed core always asks
|
|
634
|
+
(passkeys, recovery codes, deleting the account or a workspace, owners, moving the server), and a workspace's owner can switch
|
|
635
|
+
more on: [When Shapewall asks for the passkey again](#when-shapewall-asks-for-the-passkey-again). In a recovery-code session,
|
|
636
|
+
which has no passkey to confirm with, the prompt says "Add a passkey first" and links to adding one (or lets you use a passkey
|
|
637
|
+
you still have, which turns the session into a passkey session). Such a session, and one started by a passkey that is still on
|
|
638
|
+
hold, is asked for everything the workspace settings cover, whatever they are set to.
|
|
639
|
+
- **Tailnet sign-in.** On a server run with `--tailscale --tailnet-sign-in`, an account can be linked to a tailnet login and is
|
|
640
|
+
then signed in without a passkey: [Tailnet sign-in](#tailnet-sign-in).
|
|
90
641
|
- **Account activity.** The Account page lists your own security events, newest first: sign-ins (passkey or recovery code, with the
|
|
91
642
|
device and IP), passkeys added and removed, new recovery codes, devices signed out (`GET /auth/security-log?before=`). After a
|
|
92
643
|
recovery code was used on your account, the next passkey sign-in shows a banner until you dismiss it ("That was me",
|
|
93
644
|
`POST /auth/security-notice/seen`); `GET /auth/me` carries it as `securityNotice`.
|
|
94
|
-
- **Deleting your account.** Account page, "Delete account": a fresh passkey check and your handle typed back
|
|
645
|
+
- **Deleting your account.** Account page, "Delete account": a fresh passkey check (always) and your handle typed back
|
|
95
646
|
(`DELETE /auth/me` with `{ confirm, revokeTokens }`; `POST /auth/delete-account/preview` shows the plan first). Workspaces where you
|
|
96
647
|
are the only member are deleted with it; in the others you leave (your pending invites and share links are revoked, and your API
|
|
97
648
|
tokens unless you untick that). It is refused while you are the only owner of a workspace that has other people in it: make one of
|
|
@@ -114,12 +665,16 @@ Projects belong to a workspace, never to a person. Roles:
|
|
|
114
665
|
|
|
115
666
|
The console shows this table on **Access, Roles** and next to every role picker.
|
|
116
667
|
|
|
668
|
+
From 0.7.0: a member also reads their own agent usage (and that of agents they connected), and everyone reads their own
|
|
669
|
+
activity. Admins and owners read the workspace's usage, everyone's activity and the access review
|
|
670
|
+
([Usage and activity](#usage-and-activity)).
|
|
671
|
+
|
|
117
672
|
**Renaming a token.** An agent that watches a hosted board signs its comments and replies with its token's name (for a terminal
|
|
118
673
|
login, "laptop (shapewall login)"). **Rename** on the token lists (the project page and **API tokens**) gives it a human name:
|
|
119
674
|
`PATCH /api/workspaces/:ws/projects/:pid/tokens/:tid` with `{ "name": "..." }`, 1 to 60 characters, for the same people who may revoke
|
|
120
675
|
it (admins and owners). The secret, the scopes and the expiry do not change; what the token already wrote keeps the old name; a
|
|
121
|
-
revoked token is not renamed; the audit log records `token_renamed` with both names.
|
|
122
|
-
|
|
676
|
+
revoked token is not renamed; the audit log records `token_renamed` with both names. A token that may take work is an agent with an
|
|
677
|
+
icon, a state and rules of its own: see [Agents on a hosted board](#agents-on-a-hosted-board).
|
|
123
678
|
|
|
124
679
|
**Invite links** hold a 32-byte token (stored hashed), a role, an expiry (1, 3, 7, 14 or 30 days; 7 by default), and work once. Opening
|
|
125
680
|
one shows the workspace and role; a new person creates an account from it, an existing one joins with a click. The token sits in the
|
|
@@ -141,7 +696,7 @@ token has a creator. An admin removing someone may keep their tokens (`{ revokeT
|
|
|
141
696
|
kept tokens are `inactive` and refused until the creator is an admin here again, so revoke them and make new ones.
|
|
142
697
|
|
|
143
698
|
**Share links** let an admin share one project's boards with someone who has no account. They are off for every workspace until an
|
|
144
|
-
admin turns them on (Settings
|
|
699
|
+
admin turns them on (Settings); turning them off stops every link at once, and turning them back on
|
|
145
700
|
restores the ones that are not revoked or expired.
|
|
146
701
|
|
|
147
702
|
- A link reaches exactly one project. It is **view-only** or **comment** (guests give a display name, 1 to 40 characters), expires
|
|
@@ -177,7 +732,7 @@ restores the ones that are not revoked or expired.
|
|
|
177
732
|
passcodes collapse into one row per link and hour, with a count (and up to 10 guest names).
|
|
178
733
|
|
|
179
734
|
**Public projects** put one project on the open web, view-only. They are off in every workspace until an owner turns them on
|
|
180
|
-
(Settings
|
|
735
|
+
(Settings). Then an owner makes a project public on its page: it gets a public
|
|
181
736
|
id of 128 random bits and the URL `/p/<public id>/`, shown there to copy.
|
|
182
737
|
|
|
183
738
|
- Anyone with the URL sees the project's boards and comments as a view-only share link guest does, except that every guest is
|
|
@@ -197,7 +752,8 @@ Projects and Members; admins and owners see everything.
|
|
|
197
752
|
|
|
198
753
|
- **Members.** Everyone with their role, when they joined and when they were last active (updated at most every 5 minutes). Change a
|
|
199
754
|
role from the picker or remove someone from the row menu; both ask first. Admins manage members and viewers; only an owner changes
|
|
200
|
-
or removes an admin or an owner
|
|
755
|
+
or removes an admin or an owner. Anything that makes, changes or removes an owner always asks for the passkey; the same for
|
|
756
|
+
an admin when the workspace asks for it (Settings, "Members and roles"). The last owner
|
|
201
757
|
cannot be demoted, removed or leave. Removing, or demoting below admin, revokes the person's pending invites, share links and API
|
|
202
758
|
tokens (the confirm dialog says so). When the person made API tokens that still work, the remove dialog lists them with "Revoke"
|
|
203
759
|
checked; unchecking it keeps them, inactive (`DELETE /members/:user` with `{ revokeTokens: false }`); the audit entry says whose
|
|
@@ -221,13 +777,19 @@ Projects and Members; admins and owners see everything.
|
|
|
221
777
|
(`q`: names, handles, projects, tokens, links, details); 50 a page, newest first, "Load older events" for more. Each entry shows the
|
|
222
778
|
relative and the exact time. "Export CSV" downloads up to 10,000 entries with the same filters (`GET /audit/export`; cells that
|
|
223
779
|
start with `=`, `+`, `-` or `@` get a leading `'` so a spreadsheet does not run them).
|
|
780
|
+
- **Usage.** Every agent turn with the numbers each agent reported: tiles against the period before, charts, a grid of every turn,
|
|
781
|
+
saved views and exports ([Usage and activity](#usage-and-activity)).
|
|
782
|
+
- **Activity.** What people did, read from the audit log: sign-ins, settings with before and after, agents, approvals, tokens and
|
|
783
|
+
exports; a page per person and per agent; and the access review.
|
|
224
784
|
- **Settings.** Rename (admins), share links on or off (admins), public projects on (owners) or off (admins), export (admins), leave, and delete the workspace (the owner, with a
|
|
225
785
|
passkey check and the workspace name typed back). Deleting removes every project, board, file, comment, token, invite, share link and
|
|
226
786
|
audit entry, and writes one `workspace_deleted` entry to the account log.
|
|
227
|
-
- **Export.** "Download a copy" (admins
|
|
787
|
+
- **Export.** "Download a copy" (admins; `POST /export`; one at a time per workspace, 409 while one runs,
|
|
228
788
|
and 5 an hour per person) streams a zip: `workspace.json` (the workspace,
|
|
229
789
|
members, projects, tokens without their secrets, share links without theirs), `audit.json`, and per board `board.json`,
|
|
230
|
-
`comments.json` and its files (captures, variants, versions, live HTML)
|
|
790
|
+
`comments.json` and its files (captures, variants, versions, live HTML), and `chats.json` when the board has chat with a
|
|
791
|
+
[connected agent](#connected-agents): the threads every member reads (the board's and each comment's) with their messages. A
|
|
792
|
+
member's own chats are not in the copy; the file says how many there are. Over 3.5 GB it answers 413 (no zip64 yet). `audit.json` holds
|
|
231
793
|
up to 100,000 entries, newest first, read and written 1,000 at a time.
|
|
232
794
|
- A member who opens an admin page (a link, a bookmark) sees "This page needs the admin role" instead of being sent back to Projects.
|
|
233
795
|
- An empty project shows a four-step checklist (project, token, push, invite) that ticks itself off. The token dialog shows the
|
|
@@ -273,7 +835,9 @@ shapewall push --remote https://app.example.com # and comments, watch, mcp --
|
|
|
273
835
|
It prints a short code (like `BCDF-GHJK`) and opens `/device` in the browser (a URL the CLI builds from `--remote`, never one the
|
|
274
836
|
server sends; on Windows through `rundll32 url.dll,FileProtocolHandler`, no shell). Someone with the admin role there types the code,
|
|
275
837
|
checks that the page shows the same code, the address the login came from and how long ago it started, picks the workspace,
|
|
276
|
-
project, scopes and expiry (30 or 90 days, or none), and approves with a passkey check
|
|
838
|
+
project, scopes and expiry (30 or 90 days, or none), and approves (with a passkey check when the workspace asks for one
|
|
839
|
+
before "Agents and machines"). On a server with tailnet sign-in the command needs no code at all:
|
|
840
|
+
[From your coding agent](#from-your-coding-agent). The machine name is shown as reported by the
|
|
277
841
|
terminal (unchecked), and the page warns when the login came from another address than the approver's. The CLI, polling `POST /api/v1/device/poll` every 3 seconds, receives the token once and saves it
|
|
278
842
|
in `$XDG_CONFIG_HOME/shapewall/credentials.json` (or `~/.config/...`): the folder 0700, the file 0600, one entry per server origin.
|
|
279
843
|
It never prints the token. The token is named `<machine> (shapewall login)` and listed with the others; revoke it there. A code
|
|
@@ -303,14 +867,16 @@ The server treats every upload as untrusted, even from our CLI:
|
|
|
303
867
|
- Cleaning runs in worker threads (2 at once, 32 waiting, 30 seconds and 512 MB each), never on the server's event loop; a token has at
|
|
304
868
|
most 4 uploads in flight.
|
|
305
869
|
- The manifest and variants are rebuilt field by field; the board definition is validated by the same code as a local config.
|
|
306
|
-
- **
|
|
307
|
-
an MCP client) with a token of the project that has the `claim` scope.
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
870
|
+
- **Which agents are online?** A comment sent to an agent is only picked up while some machine runs `shapewall watch --remote` (or
|
|
871
|
+
an MCP client) with a token of the project that has the `claim` scope. Each such token is an agent
|
|
872
|
+
([Agents on a hosted board](#agents-on-a-hosted-board)). The server remembers, in memory, when each one last called the API or held
|
|
873
|
+
its event stream open; for 90 seconds after that the agent is online. Members who can send comments to an agent see every agent
|
|
874
|
+
by name with its state in the board's Agent panel (the Agent button in the top bar; on a phone, **Agents** in the More menu), in
|
|
875
|
+
the button's tooltip ("Builder online, Fixer offline") and on the thread. Only names, faces and times are told, never a token, and
|
|
876
|
+
never to share link guests or public viewers. After a restart every agent reads offline, with the last time it was seen, until
|
|
877
|
+
its next call.
|
|
312
878
|
- **Removing a board.** A board pushed by mistake, or one you retired, comes off the server on the project page: "Remove board"
|
|
313
|
-
on its row in the Boards list, for the same people who may delete the project (admins and owners
|
|
879
|
+
on its row in the Boards list, for the same people who may delete the project (admins and owners).
|
|
314
880
|
It deletes that board's captures, page history, variants, checks, comments, replies and comment images, and frees their storage;
|
|
315
881
|
the project, its other boards, its tokens and its share links stay. A later push of the same board id starts a new board: the
|
|
316
882
|
captures are back, the comments are not. The audit log records who removed which board, and people who have the board open are
|
|
@@ -324,7 +890,7 @@ The server treats every upload as untrusted, even from our CLI:
|
|
|
324
890
|
|
|
325
891
|
`/w/<workspace>/p/<project>/` serves the same board client as `shapewall serve`, on an API with the same shape, for members of the
|
|
326
892
|
workspace. Comments are signed with the account's name and handle (the server sets them; the board shows the handle beside the name).
|
|
327
|
-
A token's replies are signed with the token's name and marked as an agent; the API ignores any `author` it sends. Captures from the board and editing journeys are off on a
|
|
893
|
+
A token's replies are signed with the token's name and marked as an agent, with its agent's icon beside them; the API ignores any `author` it sends. Captures from the board and editing journeys are off on a
|
|
328
894
|
hosted board (push again instead). Compare between environments is not hosted yet.
|
|
329
895
|
|
|
330
896
|
Live HTML is served from `/uc/...` through HMAC-signed URLs that expire after 2 minutes. The board API gives each new frame load a
|
|
@@ -406,6 +972,968 @@ Emoji reactions are for people: members and up toggle one with `POST /api/boards
|
|
|
406
972
|
reacted), tokens have no reactions route and the token API leaves reactions out of what agents read. Reacting does not change a
|
|
407
973
|
comment's `updatedAt` or notify anyone.
|
|
408
974
|
|
|
975
|
+
### Agents on a hosted board
|
|
976
|
+
|
|
977
|
+
Every project API token with the `claim` scope is an **agent**: a named thing the board lists, that people choose when they send a
|
|
978
|
+
comment, with a state and rules about who may use it. Nothing changes on the machine that runs it: `shapewall watch --remote` and
|
|
979
|
+
`shapewall mcp --remote` work as before, with the same token, and need no new flag. The server still never runs an agent.
|
|
980
|
+
|
|
981
|
+
- **Name and face.** The agent's name is its token's name. In the console (**Agents**, then the project) **Edit** changes the name
|
|
982
|
+
(1 to 40 characters, one line), picks one of the built-in icons and a colour, and says what runs behind it (Claude Code, Codex,
|
|
983
|
+
goose, Gemini CLI, another program, or an unknown watcher). A known program shows its mark until you pick an icon; a watcher
|
|
984
|
+
whose command is unknown shows its initials. The agent's replies on a thread wear its face. A token made with `shapewall login`
|
|
985
|
+
keeps the machine's name as a label.
|
|
986
|
+
- **State.** Online (heard from in the last 90 seconds; a [connected agent](#connected-agents): while its link is open), working
|
|
987
|
+
(online and holding a comment it took, or answering in a chat), offline (with the last time it was seen) or revoked (its token was
|
|
988
|
+
revoked or expired, or its maker is no longer an admin).
|
|
989
|
+
- **Sending a comment to one agent.** **Send to agent** on a thread is a split button: the main part names the project's default
|
|
990
|
+
agent, the caret lists every agent with its state, and **Any agent** hands the comment to whichever takes it first (what every
|
|
991
|
+
comment did before 0.4.0). A comment sent to one agent can only be taken by that agent's token. The other tokens of the project do
|
|
992
|
+
not see it at all: not in lists, not by id, not through MCP.
|
|
993
|
+
- **The default agent.** An admin or owner picks it on the project's Agents page (**Make default**). It is what the main part of
|
|
994
|
+
Send to agent names, and where a trusted member's new comment goes (such a comment is sent as it is written). Without a default,
|
|
995
|
+
and for people the default does not take work from, comments go to any agent. A project starts with no default.
|
|
996
|
+
- **An agent that is offline.** The comment waits for it, and the thread and the Agent panel say so: "Waiting for Builder (offline,
|
|
997
|
+
last seen 2 hours ago)". Nothing is lost: when the agent is back it takes what was sent to it. **Let any agent take it** hands the
|
|
998
|
+
comment to whichever agent is free; **Choose another** sends it to a different one. Revoking an agent sends what waited for it to
|
|
999
|
+
any agent.
|
|
1000
|
+
- **Who may send it work (the audience).** Work sent to an agent runs on the machine of the person who connected it, so each agent
|
|
1001
|
+
says whose work it takes:
|
|
1002
|
+
|
|
1003
|
+
| Audience | Takes work from |
|
|
1004
|
+
| ------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
1005
|
+
| Only the person who connected it | That person. **The default for every agent made from 0.4.0 on** |
|
|
1006
|
+
| Named members | That person and the members you choose |
|
|
1007
|
+
| Everyone this project's agent policy trusts | The team case: whoever may send work to an agent here at all may use this one |
|
|
1008
|
+
|
|
1009
|
+
The audience only narrows: the project's **Agent policy** still decides who may send work to an agent at all. The server checks it
|
|
1010
|
+
twice, when the comment is sent (and when an admin approves someone else's run) and again when the agent's token takes it, against
|
|
1011
|
+
the person whose approval stands on the comment. The audience also decides whose replies the agent reads: a reply from someone it
|
|
1012
|
+
does not take work from never reaches its token, however trusted they are by the agent policy. An audience governs new work: a
|
|
1013
|
+
comment the agent already holds stays its own until it finishes, even if the audience is narrowed meanwhile, and sending a comment
|
|
1014
|
+
again while an agent works on it changes nothing. On the board, an agent you may not use is listed, greyed, with the reason ("Only
|
|
1015
|
+
Ada can send work to Builder. Ask them, or an admin, to share it.").
|
|
1016
|
+
**Tokens that already had the `claim` scope before 0.4.0 keep the behaviour they had**: everyone the agent policy trusts. The
|
|
1017
|
+
console marks them "kept from before 0.4.0".
|
|
1018
|
+
|
|
1019
|
+
- **Approvals.** Each agent has an approval rule and two roles: who may answer its approvals, and who may change the rule (admins and
|
|
1020
|
+
owners, or owners only; only an owner changes those two). The rule in effect is **Ask every time** unless the agent's own machine
|
|
1021
|
+
says otherwise: what an agent asks to do waits for a person with that role (and their passkey again when the workspace asks for it). **Allow without asking** is
|
|
1022
|
+
listed as not available until the agent's own machine names what may go without asking (`shapewall agent connect --approvals
|
|
1023
|
+
owner --auto edits`, on that machine). It is never the default and is never possible on the server's say alone. A
|
|
1024
|
+
[connected agent](#connected-agents) reads and answers only until its machine switches edits on
|
|
1025
|
+
([Edits from the board](#edits-from-the-board-the-trust-decision)).
|
|
1026
|
+
- **Revoke.** Revoking an agent revokes its token (and revoking the token on the Tokens page revokes the agent). What it was working
|
|
1027
|
+
on loses its "working" status and goes to any agent, with what waited for it; its usage records close as "revoked"; the project
|
|
1028
|
+
loses it as default. The same happens when an agent stops working by another road (its token expired, its maker was removed or is
|
|
1029
|
+
no longer an admin), the next time it would be seen. The audit log has one `agent_queue_released` entry per comment.
|
|
1030
|
+
- **The workspace overview.** **Agents** in the workspace menu (admins and owners) lists every agent of the workspace: the project
|
|
1031
|
+
it serves, its state, when it was last seen, who may send it work and who connected it, with a link to manage each. An agent
|
|
1032
|
+
belongs to one project; a machine that works on two projects has two tokens and so two agents.
|
|
1033
|
+
- **Audit.** `agent_created`, `agent_first_seen`, `agent_renamed`, `agent_identity_changed`, `agent_default_changed`,
|
|
1034
|
+
`agent_audience_changed`, `agent_approval_rule_changed`, `agent_revoked` and `agent_queue_released` are in the workspace's audit log
|
|
1035
|
+
with what it was before and after.
|
|
1036
|
+
- **Usage records.** For every comment an agent takes, the server writes one row: who asked, which agent, project, board and comment,
|
|
1037
|
+
when it started, when it ended and how (done, needs a person, resolved, released). No comment text and no answers. This is the
|
|
1038
|
+
groundwork of a usage page; there is nothing to look at yet, and the rows go with their project.
|
|
1039
|
+
|
|
1040
|
+
There are two ways to connect one, on the machine that has the code. An agent members **chat with** (it reads the project and
|
|
1041
|
+
answers; when its machine says so, it also makes a fix on a branch, each edit allowed on the board;
|
|
1042
|
+
[Connected agents](#connected-agents)):
|
|
1043
|
+
|
|
1044
|
+
```sh
|
|
1045
|
+
shapewall agent connect --remote https://wall.example.com # approve in the console: name it, choose the project and who may use it
|
|
1046
|
+
```
|
|
1047
|
+
|
|
1048
|
+
An agent that **fixes comments by itself** (a watcher: it runs your command once for each comment sent to it):
|
|
1049
|
+
|
|
1050
|
+
```sh
|
|
1051
|
+
shapewall login --remote https://wall.example.com # approve in the console, choose the project, tick "Take agent work"
|
|
1052
|
+
shapewall watch --remote https://wall.example.com --exec "<your agent command>"
|
|
1053
|
+
```
|
|
1054
|
+
|
|
1055
|
+
Either appears on the project's Agents page as online. Give it a name and an icon there, and choose who may send it work.
|
|
1056
|
+
[Agent recipes](agent-recipes.md) has the commands for Claude Code, Codex and goose. One machine can run both, each with its own
|
|
1057
|
+
token.
|
|
1058
|
+
|
|
1059
|
+
Console API (admins and owners): `GET /api/workspaces/:ws/agents`, `GET /api/workspaces/:ws/projects/:pid/agents`,
|
|
1060
|
+
`PATCH .../agents/:aid` (`{ name, icon, tint, kind }`), `PUT .../agents/:aid/audience` (`{ audience: "owner" | "members" | "trusted",
|
|
1061
|
+
users }`), `PUT .../agents/:aid/approval` (`{ rule, changeRole, answerRole }`), `PUT .../default-agent` (`{ agentId }`, `null` for
|
|
1062
|
+
none) and `DELETE .../agents/:aid`. Board API (members): `GET /api/boards/:board/agents`, `POST .../comments/:id/send-to-agent` takes
|
|
1063
|
+
`agentId` (an agent's id, `null` for any agent; left out, the default agent) and `POST .../comments/:id/release-agent` lets any agent
|
|
1064
|
+
take a comment that waits for one.
|
|
1065
|
+
|
|
1066
|
+
## Connected agents
|
|
1067
|
+
|
|
1068
|
+
A **connected agent** is a coding agent on a machine that has the project's code, joined to a hosted project so that members can
|
|
1069
|
+
chat with it on the board. In this release that agent is Claude Code ([which agents](#which-agents-can-be-connected)). One command
|
|
1070
|
+
connects it:
|
|
1071
|
+
|
|
1072
|
+
```sh
|
|
1073
|
+
cd ~/projects/site # the project's folder, on the machine that has the code
|
|
1074
|
+
shapewall agent connect --remote https://wall.example.com
|
|
1075
|
+
```
|
|
1076
|
+
|
|
1077
|
+
1. **The first run asks for an approval.** The command prints a short code and the address of the server's `/device` page. An admin
|
|
1078
|
+
or owner of the workspace opens it, types the code, and sees "Connect an agent": the machine's name, the address it asked from,
|
|
1079
|
+
and which agent it says it runs. They give the agent a name and an icon, choose the project, and choose who may use it. **Only
|
|
1080
|
+
me** is the default. (On a server with tailnet sign-in, run on a tailnet machine by an admin, there is no code and no
|
|
1081
|
+
browser: [From your coding agent](#from-your-coding-agent).)
|
|
1082
|
+
2. **The machine gets the agent's own token.** It is saved on that machine and never printed. The next run of the same command needs
|
|
1083
|
+
no approval.
|
|
1084
|
+
3. **The agent comes online.** It shows in the board's Agents panel and on the project's Agents page for as long as the command
|
|
1085
|
+
runs: its state comes from its open link to the server, not from a timer. Ctrl+C disconnects it.
|
|
1086
|
+
4. **Members chat with it.** The Agent button on the board opens the Agents panel. **Chat** on a connected agent opens a chat with
|
|
1087
|
+
it in the same panel a local board has: the answer streams in, with the agent's steps.
|
|
1088
|
+
|
|
1089
|
+
**By default a connected agent reads and answers. It does not change files and it runs no commands.** The machine that runs it
|
|
1090
|
+
enforces this, whatever the server sends, in two ways. The agent's own controls are set so that it cannot act: its session starts
|
|
1091
|
+
without your settings files and with only its reading tools
|
|
1092
|
+
([read-only by the agent's own controls](#read-only-by-the-agents-own-controls)). And Shapewall offers it no way to write a file
|
|
1093
|
+
or open a terminal, and refuses every permission request it makes on the spot. The answer then shows what was refused ("Refused:
|
|
1094
|
+
read and answer only"), and nobody is asked. If the session cannot be made read-only, the agent is not started. When a change is
|
|
1095
|
+
needed, the agent says what to change and where.
|
|
1096
|
+
|
|
1097
|
+
**Edits are switched on only on the machine that has the code** (Shapewall 0.6.0). Started with `--approvals owner` or
|
|
1098
|
+
`--approvals admins`, the agent can make a fix for a comment: on a new branch, in a folder of its own, never in the checkout, and
|
|
1099
|
+
each edit is a card with the full diff that a person allows or denies on the board
|
|
1100
|
+
([Edits from the board](#edits-from-the-board-the-trust-decision)). Chat stays read and answer only either way. A connected Claude
|
|
1101
|
+
Code runs no commands from the board in this release. `shapewall watch --remote --exec` is unchanged, and stays the way for an
|
|
1102
|
+
agent that fixes comments with nobody in between.
|
|
1103
|
+
|
|
1104
|
+
The server still never runs an agent. It stores the conversation and passes messages between the browser and the agent's machine.
|
|
1105
|
+
|
|
1106
|
+
### Which agents can be connected
|
|
1107
|
+
|
|
1108
|
+
Only **Claude Code** is offered by `agent connect` in this release. An agent is offered when its own controls were shown, with its
|
|
1109
|
+
real adapter, to keep a read-only session from editing, running commands and reading outside the project. Refusing what an agent
|
|
1110
|
+
asks for is not enough when it does not ask.
|
|
1111
|
+
|
|
1112
|
+
| Agent | `agent connect` | Why |
|
|
1113
|
+
| ----------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
1114
|
+
| Claude Code | Yes | Started with only its reading tools and none of your settings files, it created no file, ran no command, and asked before reading outside the project |
|
|
1115
|
+
| Codex | Refused, with a message | Started in its read-only sandbox it changed no file in our check, but it still ran shell commands and read a file outside the project without asking. What it reads can leave the machine in an answer |
|
|
1116
|
+
| goose | Refused, with a message | Its chat-only mode could not be verified on the test machine |
|
|
1117
|
+
| Gemini CLI | Refused, with a message | It was not installed to verify |
|
|
1118
|
+
|
|
1119
|
+
The same rule holds for an agent saved on the machine: it can be connected only when its command starts Claude Code. For Codex,
|
|
1120
|
+
goose and Gemini CLI, `shapewall watch --remote` stays the way to work on a hosted board. How the check was done is in
|
|
1121
|
+
[agent-hardening.md](agent-hardening.md#connected-agents).
|
|
1122
|
+
|
|
1123
|
+
The same test decided what a fix session gets. A Claude Code session for a fix has its reading tools and its editing tools, and
|
|
1124
|
+
no shell tool: started with the shell tool, Claude Code ran commands it takes to be read-only (`ls`, `cat`) without asking anyone,
|
|
1125
|
+
and those can read outside the project. So commands from the board are not offered for Claude Code in this release
|
|
1126
|
+
([Commands](#commands-are-not-offered-for-claude-code)).
|
|
1127
|
+
|
|
1128
|
+
### The connect command
|
|
1129
|
+
|
|
1130
|
+
| Flag | Default | Meaning |
|
|
1131
|
+
| --------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1132
|
+
| `--agent NAME` | This project's agent, else Claude Code when found | `claude`, or the id of an agent saved on this machine that runs Claude Code. Never a command from the server |
|
|
1133
|
+
| `--name "Builder"` | The agent's own name | The name to suggest on the approval page. The approver has the last word, and an admin can rename it later |
|
|
1134
|
+
| `--as NAME` | `default` | A second connection from this machine, with a token of its own |
|
|
1135
|
+
| `--audience owner\|server` | `server` | `owner`: the server is asked to keep it to the person who connected it even if its audience there is widened, and this machine refuses a job the server labels as someone else's. `server`: its audience on the server |
|
|
1136
|
+
| `--approvals none\|owner\|admins` | `none` | Edits from the board. `none`: never, the agent reads and answers only. `owner`: the person who connected it may allow each edit. `admins`: whoever the server lets answer (admins by default) |
|
|
1137
|
+
| `--auto none\|edits` | `none` | What the server's "Allow without asking" rule may apply to. `none`: every request waits for a person. Needs `--approvals owner` or `admins` |
|
|
1138
|
+
| `--allow-path FILE` | None | A file that runs something, which the agent may ask to edit (a dotfile, `package.json`, a `Makefile`, a `Dockerfile`, CI config). Such an edit is refused on the machine otherwise. Adds one file per run; `none` empties the list |
|
|
1139
|
+
| `--base BRANCH` | `head` | The branch a fix starts from. `head`: the commit the checkout is on, and then only while the checkout has no uncommitted changes to tracked files |
|
|
1140
|
+
| `--git-remote NAME` | `origin` | Where a finished fix is pushed. `none`: never pushed |
|
|
1141
|
+
| `--takeover` | | Close the link another process holds for this agent, and take its place |
|
|
1142
|
+
| `--concurrency N` | 2 | Answers at once, 1 to 4 |
|
|
1143
|
+
| `--token-file FILE` | | For a service: the agent's own token from a file, no browser |
|
|
1144
|
+
|
|
1145
|
+
`--approvals`, `--auto`, `--allow-path`, `--base` and `--git-remote` are saved for the connection, so the next run without them
|
|
1146
|
+
keeps what was set. They are explained under [Switching edits on](#switching-edits-on). `--allow-command` is listed by
|
|
1147
|
+
`shapewall --help` and is refused for Claude Code ([Commands](#commands-are-not-offered-for-claude-code)).
|
|
1148
|
+
|
|
1149
|
+
- **Which program runs** is the machine's choice: an agent saved for this project on that machine, or Claude Code found on its
|
|
1150
|
+
`PATH` with its ACP adapter, the same detection a local board uses ([agents.md](agents.md)). Codex, goose, Gemini CLI, a saved
|
|
1151
|
+
agent that runs one of them, a program Shapewall does not know and a model endpoint are all refused with a message. Nothing the
|
|
1152
|
+
server sends names a command, an argument, a folder or an environment variable.
|
|
1153
|
+
- **`--audience owner` trusts the server's label.** The machine cannot check who really asked: it sees only what the server says
|
|
1154
|
+
about a job. So this setting holds against a later change of the audience on the server, and does not protect against a
|
|
1155
|
+
compromised server.
|
|
1156
|
+
- **One link per agent.** One `agent connect` process holds an agent's link. A second one on the same token is refused by the
|
|
1157
|
+
server, and the command exits with an error that names the machine already connected and since when. `--takeover` closes the
|
|
1158
|
+
other link first; the process that lost it prints that another connect took over, and exits 0.
|
|
1159
|
+
- **The folder it reads** is the one the command runs in (the folder of `shapewall.config.json` when there is one). The agent
|
|
1160
|
+
process starts with a small environment and never gets `SHAPEWALL_TOKEN` or any other `SHAPEWALL_*` variable.
|
|
1161
|
+
- **The token** comes from `SHAPEWALL_TOKEN`, then `--token-file`, then the one saved by an earlier approval. It must be a connected
|
|
1162
|
+
agent's token: the login saved by `shapewall login` is never used, and a plain project token is refused with a message.
|
|
1163
|
+
- **Files on the machine.** The token is kept in `credentials.json` in Shapewall's config folder (`$XDG_CONFIG_HOME/shapewall`, by
|
|
1164
|
+
default `.config/shapewall` in your home folder), under `agents`, by server and `--as` name, apart from the login `push` and
|
|
1165
|
+
`watch` use. What the machine allows (`--audience`, `--approvals` and the flags that go with it) is remembered in
|
|
1166
|
+
`agent-policy.json` beside it, one entry per server and `--as` name. Both files are readable by you only (0600), are outside
|
|
1167
|
+
every repository, and the server cannot change either.
|
|
1168
|
+
- **Ending.** Ctrl+C or SIGTERM stops the answers in progress, closes the agent and exits 0. A token the server refuses (revoked,
|
|
1169
|
+
expired, or its maker is no longer an admin) ends the command with exit 1; a saved token is then removed, so the next run asks for
|
|
1170
|
+
a new approval.
|
|
1171
|
+
|
|
1172
|
+
One connection serves one project. A machine that works on two projects connects twice, each in its own folder (`--as docs` for the
|
|
1173
|
+
second on the same server). Connecting one agent to every project of a workspace in one step is not in this release; the workspace's
|
|
1174
|
+
**Agents** page lists every agent and the project it serves.
|
|
1175
|
+
|
|
1176
|
+
### What a connected agent's token may do
|
|
1177
|
+
|
|
1178
|
+
Approving a connection makes a project token with a fixed set of scopes: `read`, `reply`, `status`, `claim` and `agent`. It reads
|
|
1179
|
+
comments sent to it, replies as itself, sets agent statuses, takes work and holds the link. It never has `resolve` or `push`,
|
|
1180
|
+
whatever the approval asks for.
|
|
1181
|
+
|
|
1182
|
+
The `agent` scope opens the link routes and nothing else. It cannot be ticked on an ordinary token in the console or at
|
|
1183
|
+
`shapewall login`; it comes from approving `shapewall agent connect`. A token with `claim` but without `agent` (a `watch --remote`
|
|
1184
|
+
watcher) is an agent as before, with no link and no chat.
|
|
1185
|
+
|
|
1186
|
+
### Chat with a connected agent
|
|
1187
|
+
|
|
1188
|
+
- **Threads.** The **board chat** and the chat of each comment are shared: every member of the workspace reads them. A chat you
|
|
1189
|
+
start with **Chat** (or **New chat**) is yours alone: nobody else reads it, lists it, writes in it or stops it, an admin included.
|
|
1190
|
+
Agent transcripts can quote source code, so viewers, share link guests and public visitors have no chat at all.
|
|
1191
|
+
- **Who may ask.** A member the project's agent policy trusts, who is in the audience of the thread's agent, while that agent is
|
|
1192
|
+
online. Everyone else can read a shared thread, and sees why they cannot write in it ("Only Ada can use Scout").
|
|
1193
|
+
- **One answer at a time** in a thread. A second message while one is being answered is refused; the panel queues it for you.
|
|
1194
|
+
- **Stop** ends the answer. The person who asked, the person who connected the agent, and admins may stop it.
|
|
1195
|
+
- **A turn outlives the tab that started it.** Reload, or open the same shared thread as a second person: the running answer is
|
|
1196
|
+
replayed from its start, in order, and then followed live. A viewer whose stream drops resumes from the last event it has and
|
|
1197
|
+
misses nothing. Closing the tab does not stop the agent; Stop does.
|
|
1198
|
+
- **A thread stays with its agent.** The chip in the chat's header lists the project's connected agents with where each runs, or
|
|
1199
|
+
why you cannot use it. You can point a thread only at an agent you may use yourself, and a thread never moves to another agent
|
|
1200
|
+
by itself. Switching a thread that has messages adds a line to it: who switched it, from which agent to which. Only then does
|
|
1201
|
+
the other agent get the thread: the messages of people it takes work from, and none of the first agent's answers.
|
|
1202
|
+
- **History** is kept on the server: the person's messages and the agent's answers with their steps. It counts against the
|
|
1203
|
+
workspace's storage quota, is in backups, and goes when its board or project is deleted. Rename, archive and delete your own
|
|
1204
|
+
chats from the chat history; a shared thread is cleared only by an admin. A thread keeps its newest 200 messages.
|
|
1205
|
+
- **"@" mentions and text files** work as on a local board: a page, a comment, an element, a journey or a person, and up to three
|
|
1206
|
+
text files with a message. Images are not sent to a connected agent yet. Editing a sent message, asking again for an answer, answer
|
|
1207
|
+
ratings and the model and effort menus are not on hosted boards yet either.
|
|
1208
|
+
- **A chat message never edits.** Whatever a message says, and whatever the agent's machine allows, a chat turn is read and answer
|
|
1209
|
+
only. Only **Fix with** on a comment starts a turn that may edit ([Fix with an agent](#fix-with-an-agent)).
|
|
1210
|
+
|
|
1211
|
+
### Who may use a connected agent
|
|
1212
|
+
|
|
1213
|
+
The audience rules of [Agents on a hosted board](#agents-on-a-hosted-board) apply to chat exactly as they do to comments, and the
|
|
1214
|
+
project's agent policy still decides who may use any agent at all. On top of them:
|
|
1215
|
+
|
|
1216
|
+
- **The machine can narrow it.** Started with `--audience owner`, the agent's machine asks the server to keep the agent to the
|
|
1217
|
+
person who connected it, even if its audience there is widened later. The server refuses everyone else, the machine refuses a
|
|
1218
|
+
job the server labels as someone else's, and the board says what is in effect: "Only Ada (set on the agent's own machine)". The
|
|
1219
|
+
machine cannot check that label, so this does not protect against a compromised server.
|
|
1220
|
+
- **A shared thread is not a way around an audience.** What reaches an agent is only what people in its audience wrote, and its own
|
|
1221
|
+
earlier answers. A message by someone outside its audience stays in the thread for people to read and is never sent to that
|
|
1222
|
+
agent; nor are another agent's answers. The same goes for replies on a comment.
|
|
1223
|
+
- **Comments follow the audience too.** The board context an agent gets with a question holds a comment only when the person
|
|
1224
|
+
asking wrote it, or the agent holds it, or its author is in the agent's audience and the comment was sent to an agent and not
|
|
1225
|
+
to another one. That is what the token API would show that agent's token. The same rule decides the comment of a comment's
|
|
1226
|
+
thread and what an "@" mention of a comment carries: a mention of a comment the agent may not read keeps only its number.
|
|
1227
|
+
- **A share link guest's text never reaches a connected agent**: not their comments, not their replies, and not through a
|
|
1228
|
+
mention.
|
|
1229
|
+
|
|
1230
|
+
### Comments sent to a connected agent
|
|
1231
|
+
|
|
1232
|
+
A comment sent to a connected agent **by name** (Send to agent, or the project's default agent) is read and answered by it: it
|
|
1233
|
+
takes the comment, answers in the comment's chat thread where everyone can watch, posts the answer as a reply signed with its name,
|
|
1234
|
+
and sets the agent status to done. It never resolves a comment, and Send to agent never edits. When it cannot answer, it says so
|
|
1235
|
+
in a reply and marks the comment as needing a person. For a change to the code, press **Fix with** on the comment
|
|
1236
|
+
([Fix with an agent](#fix-with-an-agent)), when the agent's machine takes edits.
|
|
1237
|
+
|
|
1238
|
+
A comment sent to **any agent** is left alone by connected agents: it stays with the `watch --remote --exec` watchers that fix
|
|
1239
|
+
comments by themselves. So do not make a connected agent the project's default agent while you rely on watchers to fix new
|
|
1240
|
+
comments: every trusted member's new comment would go to an agent that answers it and waits for someone to press Fix.
|
|
1241
|
+
|
|
1242
|
+
### Edits from the board: the trust decision
|
|
1243
|
+
|
|
1244
|
+
A fix runs on someone's machine, with their login, for a comment other people wrote. So the question is: **who may make someone
|
|
1245
|
+
else's machine change files?** By default, nobody. Even the person who connected the agent cannot allow an edit from the board
|
|
1246
|
+
until they said so on that machine.
|
|
1247
|
+
|
|
1248
|
+
| Level | Where it is set | Default | What the board can cause |
|
|
1249
|
+
| --------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
1250
|
+
| Audience "only the person who connected it", `--approvals none` | The audience at the approval; `--audience owner` pins it from the machine | Yes | That person asks. The agent reads the project and answers |
|
|
1251
|
+
| Audience: named members, or everyone the agent policy trusts | On the server: the approval page, or the Agents page | Opt-in | Those members may ask too. Still read and answer only |
|
|
1252
|
+
| `--approvals owner` | On the machine | Opt-in | A fix on a new branch. Each edit waits for the person who connected the agent |
|
|
1253
|
+
| `--approvals admins` | On the machine | Opt-in | A fix on a new branch. Each edit waits for someone with the agent's answer role (admin by default), in its audience and trusted |
|
|
1254
|
+
| "Allow without asking" | On the machine (`--auto edits`), and then the agent's approval rule on the server | Opt-in, twice | Edits to ordinary source files go into the fix without a person. The fix stays on the machine: it is pushed only after a person allows "Push this fix" on its whole diff |
|
|
1255
|
+
| Commands | On the machine (`--allow-command`) | Not offered for Claude Code in 0.6.0 | Nothing: a fix session of Claude Code has no shell tool |
|
|
1256
|
+
|
|
1257
|
+
The machine's choice is the ceiling. The server can only narrow it: an audience, an answer role, a rule that asks. It can never
|
|
1258
|
+
widen it.
|
|
1259
|
+
|
|
1260
|
+
### Switching edits on
|
|
1261
|
+
|
|
1262
|
+
On the machine that has the code, in the project's folder:
|
|
1263
|
+
|
|
1264
|
+
```sh
|
|
1265
|
+
shapewall agent connect --remote https://wall.example.com --approvals owner # the person who connected it allows each edit
|
|
1266
|
+
shapewall agent connect --remote https://wall.example.com --approvals admins # whoever the server lets answer
|
|
1267
|
+
shapewall agent connect --remote https://wall.example.com --approvals none # back to read and answer only
|
|
1268
|
+
```
|
|
1269
|
+
|
|
1270
|
+
- **`--approvals owner`** takes an "allow" only from the person who connected the agent. The server enforces it, and the machine
|
|
1271
|
+
checks it again on every answer.
|
|
1272
|
+
- **`--approvals admins`** takes it from whoever the server lets answer: the agent's answer role (admin by default; an owner can
|
|
1273
|
+
make it owner), who is also in the agent's audience and trusted by the project's agent policy.
|
|
1274
|
+
- **The choice is saved** for this connection in `agent-policy.json` on the machine, beside the saved token. A service that runs
|
|
1275
|
+
the plain command keeps it. `--approvals none` switches it off again.
|
|
1276
|
+
- **`--auto edits`** names what the server's "Allow without asking" rule may apply to. Without it every request waits for a
|
|
1277
|
+
person ([Allow without asking](#allow-without-asking)).
|
|
1278
|
+
- **`--allow-path FILE`** lets the agent ask to edit one file that runs something. Without it, an edit to such a file is refused
|
|
1279
|
+
on the machine and never becomes a question ([Files that run something](#files-that-run-something)). Each run adds one file;
|
|
1280
|
+
`--allow-path none` empties the list. `.git` and Shapewall's own store can never be named. An allowed path always gets a card
|
|
1281
|
+
a person answers, whatever the approval rule says, and a fix that changes it is not pushed from the machine.
|
|
1282
|
+
- **`--base BRANCH`** is where a fix starts. Without it a fix starts from the commit the checkout is on, and a checkout with
|
|
1283
|
+
uncommitted changes to tracked files refuses the fix, because the fix would silently leave them out. `--base main` always starts
|
|
1284
|
+
from that branch, whatever the checkout holds. `--base head` goes back to the default.
|
|
1285
|
+
- **`--git-remote NAME`** is where a finished fix is pushed (`origin` by default). `--git-remote none`: never pushed.
|
|
1286
|
+
|
|
1287
|
+
`agent connect` prints what is in effect when it starts, and it says the same to the server with the code: the approval page
|
|
1288
|
+
shows what that machine asked for (read and answer only, or edits on a branch and who may allow them, "without asking" if it
|
|
1289
|
+
asked for `--auto edits`, the base branch, and that it never runs a command), marked "Reported by the terminal". The machine
|
|
1290
|
+
enforces its own rules; the server decides nothing by that report. Before it goes online, `agent connect` also opens a session
|
|
1291
|
+
with the agent (no prompt is sent) and prints which adapter version answered ([tested versions](agents.md#claude-code)).
|
|
1292
|
+
|
|
1293
|
+
The console's Agents page and the board's Agents panel say which mode an
|
|
1294
|
+
agent is in: "Reads and answers", "Edits on a branch, each allowed by the person who connected it" (or "an admin", or "an
|
|
1295
|
+
owner"), or "Edits on a branch, allowed without asking".
|
|
1296
|
+
|
|
1297
|
+
### Commands are not offered for Claude Code
|
|
1298
|
+
|
|
1299
|
+
The link and the machine's policy file know a third thing an agent could ask: to run one exact command from the machine's own
|
|
1300
|
+
list, each run allowed on the board (`--allow-command`). **This is not available for Claude Code in Shapewall 0.6.0, and Claude
|
|
1301
|
+
Code is the only agent `agent connect` offers.** So no connected agent runs a command from the board in this release.
|
|
1302
|
+
|
|
1303
|
+
The reason was found with the real adapter. Started with its shell tool, Claude Code runs commands it takes to be read-only
|
|
1304
|
+
(`ls`, `cat`) without asking anyone, and those can read outside the project. A list of allowed commands does not help when the
|
|
1305
|
+
agent does not ask. So:
|
|
1306
|
+
|
|
1307
|
+
- a fix session of Claude Code gets no shell tool at all;
|
|
1308
|
+
- `--allow-command` is refused for it, with that explanation;
|
|
1309
|
+
- commands written by hand into `agent-policy.json` are not in effect, and `agent connect` says so when it starts.
|
|
1310
|
+
|
|
1311
|
+
### Fix with an agent
|
|
1312
|
+
|
|
1313
|
+
On a hosted comment, **Fix with Builder** is offered when Builder's machine takes edits and you may use Builder. The agent must be
|
|
1314
|
+
online: a fix cannot be queued for an offline agent (Send to agent still queues). For an agent that reads and answers only the
|
|
1315
|
+
button is not offered, and one line says why: "Builder reads and answers only. Edits are switched on on its own machine".
|
|
1316
|
+
|
|
1317
|
+
Pressing it takes the comment in the agent's name and opens a turn in the comment's chat thread, where everyone can watch. The
|
|
1318
|
+
rules are the ones for sending a comment to an agent, unchanged:
|
|
1319
|
+
|
|
1320
|
+
- a trusted member vouches for the text they saw (a comment that changed since you opened it is refused: read it again);
|
|
1321
|
+
- a non-admin's run still needs an admin's **Approve agent run** where the agent policy says so. Fix makes that one flow: an
|
|
1322
|
+
admin's Fix is also their approval (with their passkey) and starts at once; a member's Fix sends the comment for approval,
|
|
1323
|
+
where admins see **Approve agent run** on it, and says to press Fix again once it is approved;
|
|
1324
|
+
- the agent's audience decides whose comment it takes;
|
|
1325
|
+
- the project's daily runs and its open-claims limit count a fix like any other claim;
|
|
1326
|
+
- one agent at a time: a comment that is already with an agent is refused.
|
|
1327
|
+
|
|
1328
|
+
The agent reads the comment as quoted, untrusted data, as always. Stop ends the fix, and cancels any card that waits.
|
|
1329
|
+
|
|
1330
|
+
### Where a fix is made
|
|
1331
|
+
|
|
1332
|
+
**Never in the checked-out tree.** The checkout is only read (`git status`, `git rev-parse`).
|
|
1333
|
+
|
|
1334
|
+
1. **A fresh copy of the base commit**, with no `.git` in it, in a folder outside the project: under your state folder,
|
|
1335
|
+
`$XDG_STATE_HOME/shapewall/agent-fixes/` (by default `.local/state/shapewall/agent-fixes/` in your home folder). It is made by
|
|
1336
|
+
the same code as a local board's [Work on a branch](agents.md#work-on-a-branch). That folder is never inside the project: when
|
|
1337
|
+
it would be (the project is your home folder, say), `agent connect` and the fix refuse and say to set `XDG_STATE_HOME` to a
|
|
1338
|
+
folder outside it. A relative `XDG_STATE_HOME` is ignored.
|
|
1339
|
+
2. **The agent edits that copy**, one allowed edit at a time ([Permission cards](#permission-cards)).
|
|
1340
|
+
3. **Shapewall itself commits the result** on a new branch, `shapewall/comment-<n>-<slug>`, with the repository's own author. No
|
|
1341
|
+
hook, filter or attribute runs. The comment's text in the commit subject is made inert first: no "@name" pings anyone and no
|
|
1342
|
+
"Fixes #12" closes anything.
|
|
1343
|
+
4. **The commit is kept only if it is exactly what was allowed.** Every changed file must have had an allowed edit and must hold
|
|
1344
|
+
exactly the bytes that were shown, with the file mode it had (a new file is not executable). Every allowed file must be in the
|
|
1345
|
+
commit. Nothing may be removed. A changed edit, an extra file, a mode change, a deletion, an allowed file Git left out: the
|
|
1346
|
+
branch is taken back and the thread says "Nothing was committed", with the files.
|
|
1347
|
+
5. **The branch is pushed** to the machine's remote when three things hold: the machine has that remote, the change touches no
|
|
1348
|
+
file that runs something ([Files that run something](#files-that-run-something)), and a person saw every edit. Otherwise it
|
|
1349
|
+
stays on the machine and the thread says why: "Not pushed", or, for a fix with an edit that went without asking, a
|
|
1350
|
+
**Push this fix** card ([Allow without asking](#allow-without-asking)).
|
|
1351
|
+
6. **A pull request is opened** when [GitHub connect](github.md) is set up on that machine. Otherwise the thread and the comment
|
|
1352
|
+
say "Fix ready on branch" with the name to copy. The link is shown as a link only when it is a pull request URL on github.com;
|
|
1353
|
+
on another GitHub host it is shown as text.
|
|
1354
|
+
7. **The folder is removed.** The branch stays.
|
|
1355
|
+
|
|
1356
|
+
A fix is refused before it starts, with a clear sentence in the thread and on the comment, when the project folder is not a Git
|
|
1357
|
+
repository, has no commit yet, has a merge in progress, or has uncommitted changes and no `--base`. A fix whose edits were all
|
|
1358
|
+
denied leaves no branch and no folder, and the comment is marked as needing a person.
|
|
1359
|
+
|
|
1360
|
+
**Stop stops all of it.** Stop is honoured between every step: after it nothing is committed, nothing is pushed, no pull request
|
|
1361
|
+
is opened, and the agent's reply on the comment says the fix was stopped, not "Fix ready". A fix that was waiting for
|
|
1362
|
+
"Push this fix" is taken back, branch and all. The one thing Stop cannot undo is a push that had already finished: then the
|
|
1363
|
+
thread says the branch exists on the remote, and no pull request follows.
|
|
1364
|
+
|
|
1365
|
+
**Copies a dead process left behind are swept.** When `agent connect` starts, and around every fix, the copies whose process is
|
|
1366
|
+
gone are removed with their records, so their branch names are free again. Ctrl+C during a fix removes its copy on the way out.
|
|
1367
|
+
|
|
1368
|
+
If files in the person's own checkout changed while the fix ran, the thread says so: "Files in the agent's own checkout changed
|
|
1369
|
+
during this fix. Check git status on its machine." Shapewall does not sandbox the agent's own tools
|
|
1370
|
+
([agent-hardening.md](agent-hardening.md#connected-agents)).
|
|
1371
|
+
|
|
1372
|
+
### Files that run something
|
|
1373
|
+
|
|
1374
|
+
Some files of a project run something once they change: on install, on build, in a test run, in CI, or the moment a branch is
|
|
1375
|
+
pushed. Shapewall keeps one list of them, used both when an edit is asked and before a push:
|
|
1376
|
+
|
|
1377
|
+
- dotfiles and everything in a dot folder (`.env`, `.npmrc`, `.github/`, `.husky/`, editor and agent settings);
|
|
1378
|
+
- dependency manifests and lockfiles (`package.json`, `package-lock.json`, `pnpm-lock.yaml`, `requirements*.txt`, `go.mod`,
|
|
1379
|
+
`Cargo.toml` and the like);
|
|
1380
|
+
- build, task and tool configuration (`Makefile`, `GNUmakefile`, `*.config.js` / `.ts` / `.mjs` / `.cjs`, `tsconfig*.json`, the
|
|
1381
|
+
jest, vitest, vite, webpack, rollup, babel, eslint and prettier files, `shapewall.config.json`);
|
|
1382
|
+
- scripts a package runs (`scripts/`, `bin/`, `tools/`, install hooks, `*.sh`);
|
|
1383
|
+
- container files (`Dockerfile*`, compose files) and CI files;
|
|
1384
|
+
- test files (`*.test.*`, `*.spec.*`, `test/`, `tests/`, `__tests__/`, `e2e/`): CI runs them.
|
|
1385
|
+
|
|
1386
|
+
For a connected agent's fix:
|
|
1387
|
+
|
|
1388
|
+
- an edit to one of them is **refused on the machine** unless the machine named that file with `--allow-path`;
|
|
1389
|
+
- a named one is **always asked**: it gets a card a person answers, even when the rule is "Allow without asking";
|
|
1390
|
+
- a fix that changes one is **never pushed from the machine**. The branch stays there for review.
|
|
1391
|
+
|
|
1392
|
+
Three more kinds are never part of a fix, named or not, because Shapewall's own commit leaves them out: files Git ignores,
|
|
1393
|
+
anything under `node_modules`, and `.gitattributes` / `.gitmodules`. An edit to one is refused when it is asked, with that reason.
|
|
1394
|
+
It is never allowed and then silently dropped.
|
|
1395
|
+
|
|
1396
|
+
### Permission cards
|
|
1397
|
+
|
|
1398
|
+
Each edit the agent asks for is checked on the machine first. It becomes a question only when all of this holds:
|
|
1399
|
+
|
|
1400
|
+
- the file is inside the fix's folder, after resolving symlinks;
|
|
1401
|
+
- it is not in `.git` and not in Shapewall's store;
|
|
1402
|
+
- it is not a file that runs something, unless the machine named it with `--allow-path`, and not a file Git would leave out of
|
|
1403
|
+
the commit ([Files that run something](#files-that-run-something));
|
|
1404
|
+
- the whole resulting file can be worked out, and the diff is small enough to show in full.
|
|
1405
|
+
|
|
1406
|
+
What fails is refused there, with the reason in the answer ("Refused on the agent's machine: ..."), and nobody is asked. What
|
|
1407
|
+
passes is shown in the comment's chat thread as a card:
|
|
1408
|
+
|
|
1409
|
+
- **The path and the full diff**, with **Allow** and **Deny**, in the machine's own words ("Edit src/app.css", "Create
|
|
1410
|
+
src/new.css"). The agent's own title for the request is never shown.
|
|
1411
|
+
- **A hash ties the answer to the card.** The card carries a hash of the turn, the card, the path, the whole diff and how long it
|
|
1412
|
+
waits. An answer must send that hash back. An answer for other content, another card or another turn is not this card's
|
|
1413
|
+
answer.
|
|
1414
|
+
- **A card waits 2 minutes** ("Push this fix": 10). That is a length of time, not a moment: the machine and the server each count
|
|
1415
|
+
it on their own clock, so the two clocks need not agree. No answer is a no. The machine's count is the one that decides: when
|
|
1416
|
+
it did not take an answer (it came too late there), the card shows as expired, never as "Allowed by", and is counted as not
|
|
1417
|
+
allowed.
|
|
1418
|
+
- **Who reads the diff.** The diff is a piece of the project's code. It is shown, live and in the stored thread, to the people
|
|
1419
|
+
the agent works for: those in its audience whom the project trusts, whoever may answer its cards, and whoever asked for the
|
|
1420
|
+
fix. Everyone else who can open the thread reads that the agent asked to edit a file, which file, and how that ended.
|
|
1421
|
+
- **A card is answered once.** Stop cancels the cards that wait.
|
|
1422
|
+
- **Everyone with the thread open sees the state change live**: waiting, allowed and by whom, denied, expired, cancelled. The strip
|
|
1423
|
+
above the board lists the cards that wait for you, and opens the comment's chat, where the diff is.
|
|
1424
|
+
- **Allow asks for a passkey again only when the workspace says so** (Settings, "Agent edits and pushes"; off by default). The
|
|
1425
|
+
browser asks when the server does. Deny never does: it only ever stops something.
|
|
1426
|
+
|
|
1427
|
+
**Who may answer.** Someone with the agent's answer role (admin by default), who is also in the agent's audience and trusted by
|
|
1428
|
+
the project's agent policy. When the agent's machine says `--approvals owner`: only the person who connected it. Everyone else
|
|
1429
|
+
sees the card and who it waits for.
|
|
1430
|
+
|
|
1431
|
+
**The machine checks every answer again.** It counts an "allow" only for a card it asked and still waits on, with the same hash,
|
|
1432
|
+
not expired, once, and from the connecting person when it said "owner". A failed "allow" is a deny. An answer for a card it never
|
|
1433
|
+
asked is ignored. In the other direction, the server never takes "approved" from the machine: only a person's answer on the board
|
|
1434
|
+
makes a card allowed.
|
|
1435
|
+
|
|
1436
|
+
### Allow without asking
|
|
1437
|
+
|
|
1438
|
+
Each agent has an approval rule, in the console's approvals dialog on the project's Agents page: **Ask every time** or **Allow
|
|
1439
|
+
without asking**.
|
|
1440
|
+
|
|
1441
|
+
- **Only when the agent's own machine named a kind** with `--auto` (`--auto edits`). Otherwise the option is listed as not
|
|
1442
|
+
available, with the command to run on that machine.
|
|
1443
|
+
- **Who may switch it on.** When the machine says `--approvals owner`: only the person who connected the agent, nobody else,
|
|
1444
|
+
whatever their role. An admin cannot take that person out of the loop; the server refuses, and the machine itself only goes
|
|
1445
|
+
without asking when the server says the rule is that person's own. When the machine says `--approvals admins`: the role in the
|
|
1446
|
+
agent's "who may change the rule" setting (admin by default; an owner can make it owner).
|
|
1447
|
+
- **Only for the kinds the machine named, and only for ordinary source files.** A file that runs something
|
|
1448
|
+
([Files that run something](#files-that-run-something)) always waits for a person, named or not.
|
|
1449
|
+
- **It never widens what may be edited.** The machine's checks above run on every edit all the same. The fix is still made on a
|
|
1450
|
+
branch, and the commit is still kept only when it is exactly what was allowed.
|
|
1451
|
+
- **Nothing reaches a remote without a person having seen the diff.** A fix with an edit that went without asking is committed
|
|
1452
|
+
on its branch on the machine and held there. It is not pushed and no pull request is opened. The thread shows one
|
|
1453
|
+
**Push this fix** card with the whole changed-files diff. Someone who may answer the agent's cards allows it,
|
|
1454
|
+
under the same rules as any card (the hash, once, the machine's own recheck); it waits 10 minutes. Denied or not
|
|
1455
|
+
answered, the fix stays on the machine and the result offers **Push this fix** again, as often as needed. A fix too large to
|
|
1456
|
+
show in full cannot be pushed from the board at all.
|
|
1457
|
+
- **If the machine connects again without it**, the stored rule is set back to "ask" at once, and that is in the audit log.
|
|
1458
|
+
|
|
1459
|
+
An edit that went without asking is still a card in the thread, marked "Allowed automatically", and is counted and audited.
|
|
1460
|
+
|
|
1461
|
+
### What the machine enforces whatever the server says
|
|
1462
|
+
|
|
1463
|
+
- **The command is the machine's.** The server cannot name, change or add a command, an argument, a folder, an environment
|
|
1464
|
+
variable or an MCP server.
|
|
1465
|
+
- **No edits unless this machine said so.** With `--approvals none`, nobody's answer is taken and no fix starts.
|
|
1466
|
+
- **A fix is never made in the checkout.** A fresh copy, a new branch, a folder that is removed afterwards.
|
|
1467
|
+
- **Every edit is checked here first**: inside the fix's folder, not `.git`, not Shapewall's store, not a file that runs something
|
|
1468
|
+
unless named with `--allow-path`, not a file Git would leave out, the whole diff shown.
|
|
1469
|
+
- **A file that runs something is never allowed without asking**, and a fix that changes one is never pushed.
|
|
1470
|
+
- **The policy file fails narrow.** A value in `agent-policy.json` that this version does not know (a typo, `false`, `""`, a
|
|
1471
|
+
wrong type) reads as the narrowest setting for that key, never as the default: no approvals, only the person who connected it,
|
|
1472
|
+
never pushed, nothing without asking. `agent connect` names each such key when it starts. The file must be yours and not
|
|
1473
|
+
writable by others, which is checked before it is read.
|
|
1474
|
+
- **Every answer is checked here again**: a card this machine asked, the same hash, in time, once, and from the connecting person
|
|
1475
|
+
under `--approvals owner`.
|
|
1476
|
+
- **"Allow without asking" only for what `--auto` named**, and under `--approvals owner` only when the server says the
|
|
1477
|
+
connecting person set that rule themself.
|
|
1478
|
+
- **The commit is exactly what was allowed**, byte for byte and mode for mode, or there is no commit.
|
|
1479
|
+
- **Nothing is pushed that runs something, or that no person has seen.**
|
|
1480
|
+
- **After Stop, nothing more happens**: no commit, no push, no pull request.
|
|
1481
|
+
- **No commands for Claude Code.** Its fix session has no shell tool.
|
|
1482
|
+
- **The agent never holds its token.** Its process gets a small environment with no `SHAPEWALL_*` variable.
|
|
1483
|
+
|
|
1484
|
+
What the machine cannot do is in [agent-hardening.md](agent-hardening.md#connected-agents): it does not sandbox the agent's own
|
|
1485
|
+
tools, and with approvals on, a server that was broken into can forge an "allow" for an edit the agent really asked.
|
|
1486
|
+
|
|
1487
|
+
### When a connected agent is offline
|
|
1488
|
+
|
|
1489
|
+
- **Chat is refused.** The composer gives way to "Builder is offline. Chat needs it online; a comment sent to it waits until it is
|
|
1490
|
+
back." A conversation that silently queues is worse than a clear no.
|
|
1491
|
+
- **A fix cannot be asked.** Fix with an agent needs the agent online, and is not queued.
|
|
1492
|
+
- **The thread does not move by itself.** A thread whose agent is offline, or was revoked, stays with it. When another agent you
|
|
1493
|
+
may use is online, the panel offers **Ask Scout instead**. Choosing it switches the thread in the open, with the line described
|
|
1494
|
+
under [Chat with a connected agent](#chat-with-a-connected-agent).
|
|
1495
|
+
- **Comments wait**, as for any agent: "Waiting for Builder (offline, last seen 2 hours ago)", with **Let any agent take it**. The
|
|
1496
|
+
agent takes what was sent to it when it is back.
|
|
1497
|
+
|
|
1498
|
+
### When the link drops
|
|
1499
|
+
|
|
1500
|
+
- **The link reconnects by itself**, waiting 1 to 60 seconds between tries. After every reconnect the machine asks the server what
|
|
1501
|
+
is open and picks up from there. A batch of an answer the server did not hear is sent again; a repeat is dropped.
|
|
1502
|
+
- **The machine goes away mid-answer.** After 45 seconds without a word and without a link, the turn ends as interrupted, with what
|
|
1503
|
+
the agent had written so far: "The agent's machine went away before it finished. Ask again."
|
|
1504
|
+
- **The server restarts.** Answers in progress are over. Every turn a stop left queued or running is ended as interrupted when
|
|
1505
|
+
the server starts, with its usage record, whether or not anyone opens its thread again. Stored messages are untouched.
|
|
1506
|
+
- **The agent is revoked** (on the Agents page, or its token on the Tokens page). Its link closes at once, what it was answering ends
|
|
1507
|
+
with "Builder was revoked before it finished.", and the command on its machine exits.
|
|
1508
|
+
- **A second connect.** Refused while the first holds the link, or it takes over with `--takeover`
|
|
1509
|
+
([the connect command](#the-connect-command)). After a hard crash the server may still believe the old link is open for a short
|
|
1510
|
+
while, and refuses a restart until it notices.
|
|
1511
|
+
- **A link that flaps** does not flood anything. Boards are told that an agent came or went at most once every 3 seconds per
|
|
1512
|
+
agent, and the audit log gets at most one connected and one disconnected entry a minute per agent. A revoked or taken-over link
|
|
1513
|
+
is always written.
|
|
1514
|
+
|
|
1515
|
+
### Limits of chat
|
|
1516
|
+
|
|
1517
|
+
| What | Limit |
|
|
1518
|
+
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
1519
|
+
| Messages one person sends | 20 a minute |
|
|
1520
|
+
| Chat turns in a project | 200 a day (`dailyTurns` in the agent policy) |
|
|
1521
|
+
| Answers one agent gives at once | `--concurrency` (1 to 4), plus 5 waiting; after that it answers "busy" |
|
|
1522
|
+
| A message | 8,000 characters, 8 mentions, 3 text files of 100 KB |
|
|
1523
|
+
| An answer | 100,000 characters |
|
|
1524
|
+
| What the machine sends at once | 256 KB and 100 events in a batch |
|
|
1525
|
+
| What the machine fetches for a turn | 2 MB |
|
|
1526
|
+
| Links one agent token holds | 1 (a second is refused, or takes over with `--takeover`) |
|
|
1527
|
+
| Link opens by one agent token | 6 a minute |
|
|
1528
|
+
| Chats of your own on one board | 50 (the shared threads are apart) |
|
|
1529
|
+
| A permission card | Waits 2 minutes ("Push this fix": 10); the whole diff must fit in the card; counts against the storage quota |
|
|
1530
|
+
| Cards one fix may ask | 60, and 5 waiting at the same time |
|
|
1531
|
+
|
|
1532
|
+
The daily budget is counted from the usage records, so deleting a thread gives no turns back. `dailyTurns` is part of the
|
|
1533
|
+
project's agent policy. The console's form has no field for it yet (and keeps the value when you save
|
|
1534
|
+
the form): read the policy with `GET /api/workspaces/:ws/projects/:pid/agent`, set `dailyTurns` (0 to 100000; 0 stops chat turns)
|
|
1535
|
+
and `PUT` the whole policy back. The link has its own request budget on the token API, so a streamed answer does not use up the
|
|
1536
|
+
agent's budget for comments.
|
|
1537
|
+
|
|
1538
|
+
### Running a connected agent as a service
|
|
1539
|
+
|
|
1540
|
+
Run the command once by hand in the project's folder and approve it: the token is saved. A service then runs the same command and
|
|
1541
|
+
finds it. Shapewall installs nothing; this is a systemd user unit you write yourself (`systemctl --user enable --now
|
|
1542
|
+
shapewall-agent`):
|
|
1543
|
+
|
|
1544
|
+
```ini
|
|
1545
|
+
# ~/.config/systemd/user/shapewall-agent.service
|
|
1546
|
+
[Unit]
|
|
1547
|
+
Description=Shapewall connected agent (Builder)
|
|
1548
|
+
After=network-online.target
|
|
1549
|
+
|
|
1550
|
+
[Service]
|
|
1551
|
+
WorkingDirectory=%h/projects/site
|
|
1552
|
+
ExecStart=/usr/bin/env shapewall agent connect --remote https://wall.example.com --takeover
|
|
1553
|
+
Restart=on-failure
|
|
1554
|
+
RestartSec=10
|
|
1555
|
+
# A clean environment: only what the agent needs to find its programs and its own login.
|
|
1556
|
+
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin
|
|
1557
|
+
|
|
1558
|
+
[Install]
|
|
1559
|
+
WantedBy=default.target
|
|
1560
|
+
```
|
|
1561
|
+
|
|
1562
|
+
- `--takeover` is there so a restart is not refused: after a hard crash the server may still count the old link as open for a short
|
|
1563
|
+
while. It also means this service takes the link from any other process that holds it for this agent.
|
|
1564
|
+
- With the token in a file of its own (a secret store, another user), add `--token-file /path/to/token`. The file holds the agent's
|
|
1565
|
+
token and nothing else.
|
|
1566
|
+
- SIGTERM is a clean stop (exit 0), so `systemctl --user stop` does not count as a failure. A revoked token exits 1; the unit then
|
|
1567
|
+
restarts and fails again until you approve a new connection by hand.
|
|
1568
|
+
- Give the service its own agent profile ([what it can read](#what-a-connected-agent-can-reach)).
|
|
1569
|
+
|
|
1570
|
+
### What a connected agent can reach
|
|
1571
|
+
|
|
1572
|
+
- **The server cannot make the machine act.** Every request goes out from the machine, to the one server you named. A turn's job is
|
|
1573
|
+
data: the conversation and the board around it. Nothing in it names a command, a tool, a file to write or a variable, and fields
|
|
1574
|
+
the machine does not know are dropped.
|
|
1575
|
+
- **Board text is quoted on the machine.** Comments, replies, page titles, mentions and attached files reach the agent as
|
|
1576
|
+
`<shapewall-data trust="untrusted">`, built on the machine itself, with the same rules the local chat gives an agent. Only the
|
|
1577
|
+
person's own message is outside the quotes.
|
|
1578
|
+
- **It can read the project, and its answers leave the machine.** The agent reads with its own tools: every file in the project
|
|
1579
|
+
folder that those tools can read, a `.env` file included. Its instructions say not to quote secrets, and the machine removes the
|
|
1580
|
+
agent's own token from anything it sends; neither is a guarantee. Connect only a project whose code the agent's audience may
|
|
1581
|
+
read, and keep secrets out of the folder or out of the agent's reach.
|
|
1582
|
+
- **It cannot act, by its own controls.** The session has only its reading tools and none of your settings files, and it is not
|
|
1583
|
+
started when that cannot be set up ([read-only by the agent's own controls](#read-only-by-the-agents-own-controls)). A fix
|
|
1584
|
+
session, on a machine that switched edits on, also has its editing tools, in a folder of its own.
|
|
1585
|
+
- **What leaves the machine when edits are on**, beyond the answers: the diffs on edit cards (bounded: a diff too large to show
|
|
1586
|
+
in full is refused), the file paths and line counts of a fix, the branch name and the pull request link. Still not the agent's
|
|
1587
|
+
token, which is never in the agent's environment, and not absolute paths.
|
|
1588
|
+
- **What the machine sends back** is cleaned by the server field by field before anything is shown or stored. A stolen agent token
|
|
1589
|
+
can pose as the agent (read what was sent to it, post answers); it cannot reach the machine.
|
|
1590
|
+
|
|
1591
|
+
### Read-only by the agent's own controls
|
|
1592
|
+
|
|
1593
|
+
Refusing what an agent asks for is not enough: a tool it is set up to run without asking never asks. So a connected Claude Code
|
|
1594
|
+
session is started in a way that leaves it nothing to act with, and anything that cannot be set up that way stops the start
|
|
1595
|
+
(fail closed).
|
|
1596
|
+
|
|
1597
|
+
- **No settings files.** Your `~/.claude/settings.json` and the project's `.claude/settings.json` and
|
|
1598
|
+
`.claude/settings.local.json` are left out of the session. Their allow rules, hooks, default mode and plugins do not apply.
|
|
1599
|
+
When one of them holds such rules, `agent connect` says so: "Left out of this session".
|
|
1600
|
+
- **No MCP servers** from `.mcp.json` or from settings.
|
|
1601
|
+
- **Only its reading tools:** Read, Grep and Glob. Bash, Edit, Write, MultiEdit, NotebookEdit, WebFetch, WebSearch, Task/Agent and
|
|
1602
|
+
Skill are removed from the session, and bypassing permissions is switched off.
|
|
1603
|
+
- **A mode that asks.** The session's mode must be "default" or "plan". Any other is switched to "default", or the agent is not
|
|
1604
|
+
started. An agent that reports no session mode at all is not started read-only. An agent that switches itself to another mode
|
|
1605
|
+
mid-answer is stopped.
|
|
1606
|
+
- **Reading outside the project asks**, and the request is refused like every other.
|
|
1607
|
+
- **Managed settings cannot be left out.** When `/etc/claude-code/managed-settings.json` allows acting tools (Bash, Edit, Write,
|
|
1608
|
+
MultiEdit, NotebookEdit, WebFetch, WebSearch, Task, `mcp__*`, or Read of absolute or home paths) or runs hooks, `agent connect`
|
|
1609
|
+
refuses to start and says why. It no longer only warns.
|
|
1610
|
+
- **What this costs you.** Settings that live in those files, such as an `apiKeyHelper` or `env`, do not apply to the connected
|
|
1611
|
+
session either. The login itself is not in those files.
|
|
1612
|
+
|
|
1613
|
+
**A fix session** (a machine started with `--approvals owner` or `admins`) is set up the same way, with one difference: it keeps
|
|
1614
|
+
Edit, Write and MultiEdit beside Read, Grep and Glob. It has no settings files, no MCP servers, no Bash, no web tools and no
|
|
1615
|
+
bypass. Each edit it makes asks first, and the request goes through the machine's checks and a card
|
|
1616
|
+
([Permission cards](#permission-cards)). Chat turns on the same machine keep the read-only session.
|
|
1617
|
+
|
|
1618
|
+
This was shown on one machine with one adapter version ([agent-hardening.md](agent-hardening.md#connected-agents) says how). It
|
|
1619
|
+
is still a good idea to give a connected agent a profile of its own: a separate config folder, logged in for this purpose.
|
|
1620
|
+
|
|
1621
|
+
### Chat usage records and the audit log
|
|
1622
|
+
|
|
1623
|
+
Every chat turn writes one usage record: who asked, which agent, the board and thread (or comment), when it started and ended, and
|
|
1624
|
+
how it ended (answered, stopped, failed, interrupted). The model, the effort and the token counts are kept only when the agent
|
|
1625
|
+
reports them, and a cost only when the agent itself reports one: nothing is estimated, and "not reported" is not zero. A record
|
|
1626
|
+
never holds a message or an answer. They are shown on the Usage page: see [Usage and activity](#usage-and-activity).
|
|
1627
|
+
|
|
1628
|
+
A fix is one usage record of kind "fix": its steps, how it ended (fix ready, answered, stopped, failed, interrupted), and how many
|
|
1629
|
+
requests it asked and how many were allowed and denied.
|
|
1630
|
+
|
|
1631
|
+
The audit log gains `agent_connected` (who approved which agent, on which machine, for whom), `agent_link_connected` and
|
|
1632
|
+
`agent_link_disconnected` (with the reason; at most one of each a minute per agent, except a revoked or taken-over link, which is
|
|
1633
|
+
always written), `chat_thread_created`, `chat_thread_deleted`, `chat_thread_agent_changed` (who switched a thread from which agent
|
|
1634
|
+
to which), `agent_turn_started` and `agent_turn_stopped` (who, which agent, which board and thread). No entry holds message text.
|
|
1635
|
+
|
|
1636
|
+
For edits (Shapewall 0.6.0) it gains:
|
|
1637
|
+
|
|
1638
|
+
| Entry | What it records |
|
|
1639
|
+
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
|
|
1640
|
+
| `agent_edit_mode_changed` | What the agent's machine allows changed (approvals, how many commands, what may go without asking), before and after |
|
|
1641
|
+
| `agent_turn_started` with kind "fix" | Who pressed Fix, for which agent, board and comment thread |
|
|
1642
|
+
| `agent_permission_asked` | A card arrived: the agent, the thread, the path, the card's hash |
|
|
1643
|
+
| `agent_permission_approved`, `agent_permission_denied` | Who answered, the path, the card's hash |
|
|
1644
|
+
| `agent_permission_expired` | Nobody answered in time |
|
|
1645
|
+
| `agent_permission_auto` | An edit went without asking, under the agent's rule |
|
|
1646
|
+
| `agent_permission_not_taken` | The machine did not take a person's "allow" (it came too late there): who answered, and what the card became |
|
|
1647
|
+
| `agent_fix_branch_ready` | The branch name and how many files, as the agent's machine reported them |
|
|
1648
|
+
| `agent_branch_pushed`, `agent_pull_request_opened` | The remote, or the pull request's link, as the agent's machine reported them |
|
|
1649
|
+
| `agent_approval_rule_changed` | The rule or its roles changed, by a person, or reset to "ask" because the machine no longer allows "without asking" |
|
|
1650
|
+
|
|
1651
|
+
A command would be recorded only as a hash. No entry ever holds file content or a diff. The server sees no repository: what it
|
|
1652
|
+
writes about a branch, a push or a pull request is the machine's own account.
|
|
1653
|
+
|
|
1654
|
+
### The link and chat APIs
|
|
1655
|
+
|
|
1656
|
+
The link is on the token API, scope `agent`: `POST /api/v1/agent/hello`, `GET /api/v1/agent/link` (server-sent events: `work`,
|
|
1657
|
+
`cancel`, `change`, a keepalive every 15 seconds), `GET /api/v1/agent/work`, `GET /api/v1/agent/turns/:id`,
|
|
1658
|
+
`POST /api/v1/agent/turns/:id/events` (`{ seq, events }`), `POST /api/v1/agent/turns/:id/finish` (`{ seq, message }`) and
|
|
1659
|
+
`POST /api/v1/agent/turns` (`{ board, comment }`, for a comment the agent holds). Every route derives the project and the agent from
|
|
1660
|
+
the token; another agent's turn answers 404.
|
|
1661
|
+
|
|
1662
|
+
Chat is on the board API for members and up (`/w/:ws/p/:pid/api`): `GET agent/status`, `GET agent/boards/:board/threads`,
|
|
1663
|
+
`GET|PATCH|DELETE agent/boards/:board/threads/:thread`, `POST .../threads/:thread/messages` (answers with server-sent events),
|
|
1664
|
+
`GET .../threads/:thread/events?after=<n>` (a running turn, for a second viewer), `POST .../threads/:thread/stop` and
|
|
1665
|
+
`POST .../threads/:thread/profile` (`{ profileId }`: the thread's agent). The board's agent list (`GET /api/boards/:board/agents`)
|
|
1666
|
+
says for each agent whether it is connected, whether it chats, and whether you may chat with it now. It also says which edit mode
|
|
1667
|
+
the agent is in, and whether you may press Fix and answer its cards, with the reason when not.
|
|
1668
|
+
|
|
1669
|
+
Fix with an agent is `POST .../threads/comment-<n>/messages` with `{ fix: true }` (and `agentId` for an agent other than the
|
|
1670
|
+
thread's, `dispatchHash` for the text you saw). A card is answered with `POST .../threads/:thread/permissions/:id`
|
|
1671
|
+
(`{ optionId: "allow" | "deny", hash }`), and `GET agent/boards/:board/permissions` lists the cards that wait for you.
|
|
1672
|
+
|
|
1673
|
+
## Usage and activity
|
|
1674
|
+
|
|
1675
|
+
Two pages of the Workspace Console (Shapewall 0.7.0) answer two different questions. **Usage** is about agents: every turn an
|
|
1676
|
+
agent ran, with the numbers it reported. **Activity** is about people: who signed in, who changed what, who answered which
|
|
1677
|
+
approval. Activity is read from the audit log, which stays the security record; the two pages link to each other and are never
|
|
1678
|
+
merged.
|
|
1679
|
+
|
|
1680
|
+
To look before you install: the live demo has both pages, with about sixty days of made-up numbers
|
|
1681
|
+
([Usage](https://shapewall.com/demo/console.html#/w/ws_4c756d000000000000000001/usage),
|
|
1682
|
+
[Activity](https://shapewall.com/demo/console.html#/w/ws_4c756d000000000000000001/activity)). There the queries run in your browser over
|
|
1683
|
+
a fictional history; everything on this page describes a real server.
|
|
1684
|
+
|
|
1685
|
+
### What a usage record holds
|
|
1686
|
+
|
|
1687
|
+
One row per agent turn: a chat answer, a comment an agent answered, a fix, or the push of a fix. It is written when the turn
|
|
1688
|
+
starts and completed when it ends.
|
|
1689
|
+
|
|
1690
|
+
| Recorded | Where it comes from |
|
|
1691
|
+
| ------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
1692
|
+
| When it started and ended, how long | The server's own clock, from the question to the end of the turn |
|
|
1693
|
+
| Who asked | The signed-in person (nobody, when an agent took a queued comment by itself) |
|
|
1694
|
+
| Which agent, on which machine | The agent and the machine label it connected with; and who connected it |
|
|
1695
|
+
| Project, board, thread or comment | Ids. A private chat's id is shown only to the person who started it |
|
|
1696
|
+
| Kind | Chat, comment answer, fix or push |
|
|
1697
|
+
| Outcome | Answered, fix ready, needs a person, stopped, failed, interrupted, and a few "let go" states |
|
|
1698
|
+
| Model and effort | As the agent reported them |
|
|
1699
|
+
| Input, output and cached tokens | As the agent reported them |
|
|
1700
|
+
| Context used, of how much | As the agent reported it |
|
|
1701
|
+
| Cost | Only when the agent or its endpoint reported a cost |
|
|
1702
|
+
| Steps, and tool calls counted by type | The number of steps and a count per tool type ("read: 12, edit: 3"). Never a label or an argument |
|
|
1703
|
+
| Approvals | How many it asked, how many were allowed, how many without asking, how many denied, and by whom |
|
|
1704
|
+
| The agent's own time | How long the agent says it worked, when it says |
|
|
1705
|
+
|
|
1706
|
+
**Never recorded:** the question, the answer, file contents, file names from a step, a diff or a command. Those are in the thread,
|
|
1707
|
+
which has its own access rule (members and up; a private chat only its starter). A usage row links to the comment or board for
|
|
1708
|
+
people who may read it there.
|
|
1709
|
+
|
|
1710
|
+
**Nothing is estimated.** Shapewall has no table of model prices. Subscription CLIs often report tokens and no cost, and some
|
|
1711
|
+
agents report nothing. Wherever a number was not reported the pages say "Not reported" (a dash in a table, a hatched area in a
|
|
1712
|
+
chart), never zero, and each total says how many of its turns reported the number ("723 of 1,795 turns reported").
|
|
1713
|
+
|
|
1714
|
+
### The Usage page
|
|
1715
|
+
|
|
1716
|
+
`/w/<workspace>/usage`. Everything on it follows one filter, shown in one row above it:
|
|
1717
|
+
|
|
1718
|
+
- **Period:** today, the last 7, 30 or 90 days, this week, this month, last month, or a custom range of up to 400 days. Days,
|
|
1719
|
+
weeks and months are in your browser's time zone (the server stores UTC), across any number of clock changes, north or south.
|
|
1720
|
+
Weeks start on Monday.
|
|
1721
|
+
- **Agent, project, person, kind, model, outcome:** several values each. "No model reported" and "nobody" are values too.
|
|
1722
|
+
- **Ranges** of tokens and of duration, and a **search over ids** (a turn, an agent, a project, a board, a comment number).
|
|
1723
|
+
|
|
1724
|
+
The filters live in the page's address, so a link is a view and Back undoes a filter.
|
|
1725
|
+
|
|
1726
|
+
**Overview** is a dashboard of widgets, which each person arranges for themselves ([Arranging the
|
|
1727
|
+
dashboard](#arranging-the-dashboard)). Unless you change it, it shows, for that filter:
|
|
1728
|
+
|
|
1729
|
+
- **Tiles:** turns, tokens, agent time, reported cost, fixes that ended ready, and the share that failed or was stopped, each with
|
|
1730
|
+
its change against the period to compare with, which the tile names: the same number of days just before (whole local days,
|
|
1731
|
+
whatever the clocks did); this week or this month so far against last week or last month up to the same day; last month against
|
|
1732
|
+
the month before.
|
|
1733
|
+
- **Usage over time:** stacked bars per day, week or month, split by agent, project, person, kind, model or outcome, measuring
|
|
1734
|
+
turns, tokens (total, input, output, cached), time or reported cost. Drag the bar under the chart to zoom, then "Use ... for the
|
|
1735
|
+
page" to keep that range.
|
|
1736
|
+
- **A breakdown:** ranked bars with each group's share.
|
|
1737
|
+
- **How turns ended** as a share per day, **approvals** (allowed by a person, allowed without asking, denied), and **turn
|
|
1738
|
+
duration** (the median and the 95th percentile; the 90th and 99th are an option).
|
|
1739
|
+
- **Top lists:** the busiest agents, the threads that used the most tokens, the slowest turns, the agents with the most denied
|
|
1740
|
+
approvals (five entries each; three or ten are an option).
|
|
1741
|
+
- **Budgets today** (admins and owners): each project's daily chat turns and fixes from its agent policy, with today's use, last
|
|
1742
|
+
week's daily average, and a forecast for the end of the day once a third of the day has passed and there are at least five
|
|
1743
|
+
turns to go by. The day is UTC, as the policy counts it. There are no per-agent budgets yet.
|
|
1744
|
+
|
|
1745
|
+
Hovering (or tapping) a chart shows exact values. Pressing a bar, a row of the breakdown or a legend entry filters the whole page
|
|
1746
|
+
to it. Every chart has a table of the same numbers, "copy as CSV" and "copy as an image". The colours are one palette, checked for
|
|
1747
|
+
colour-blind readers in light and dark, and never the only sign: legends carry names, outcomes carry icons.
|
|
1748
|
+
|
|
1749
|
+
**Turns** is every turn of the filter in a grid: sorted, filtered and paged by the server (a hundred rows at a time as you
|
|
1750
|
+
scroll, by a cursor, so the last page costs what the first does). Choose columns, drag a header to move its column and drag its right edge to resize it (each header's menu does both from the
|
|
1751
|
+
keyboard: move left or right, wider, narrower), pin columns to the left, sort by time, duration, tokens or cost, group by any
|
|
1752
|
+
dimension with subtotals, and switch to denser rows. With groups on, **Compare** adds two columns to the group rows: the group's
|
|
1753
|
+
turns in the period before, and the change. While you page through a sorted table it holds still: a turn that finishes meanwhile
|
|
1754
|
+
keeps the place it had when the first page was read, and turns that started later wait for the next look. Arrow keys move
|
|
1755
|
+
through the rows and Enter opens one. A turn opens in a drawer with everything in the table above, a link to its comment or board, and for
|
|
1756
|
+
admins a link to the activity around it. On a phone the grid is a list of cards and the drawer is a sheet.
|
|
1757
|
+
|
|
1758
|
+
**Saved views** are yours alone: a name for the page's address (filters, columns, sort) and, for a view saved from the overview,
|
|
1759
|
+
the dashboard as you have it: its layout and every widget's options (measure, split, bucket and the rest). Untick **Include this
|
|
1760
|
+
layout** to save the filters alone. "Copy a link to this view" shares the address; whoever opens it sees what they themselves may
|
|
1761
|
+
see, so a link or a view never widens access. Opening a view that carries a layout only ever shows that layout; your own stays as
|
|
1762
|
+
it is. For one of your own views a small chip says which view you are looking at, with "Back to my layout". For a view somebody
|
|
1763
|
+
shared by link, a note says whose layout it is, with "Use this layout" (which makes it yours) and "Back to my layout". Links and
|
|
1764
|
+
views made before the dashboard could be arranged, which name a chart's measure, split or bucket in the address (`metric=`, `by=`,
|
|
1765
|
+
`bucket=`, `bd=`), still set the first chart over time and the first breakdown.
|
|
1766
|
+
|
|
1767
|
+
**Print** prints the overview as a report (the period and filters at the top), the widgets one after another in reading order,
|
|
1768
|
+
each as tall as it needs, whatever sizes they have on screen. **Export** downloads the turns of the filter as CSV
|
|
1769
|
+
or JSON: streamed, newest first, at most 50,000 rows, with an audit entry (`usage_exported`: who, the format, how many rows, the
|
|
1770
|
+
period). There are no scheduled or emailed exports.
|
|
1771
|
+
|
|
1772
|
+
### Arranging the dashboard
|
|
1773
|
+
|
|
1774
|
+
**Edit layout** (in the page's header; **Done** or Escape leaves it) turns the overview into a grid you arrange. Every tile,
|
|
1775
|
+
chart and list is a widget on 12 columns:
|
|
1776
|
+
|
|
1777
|
+
- **Move** a widget by dragging the bar it wears while you edit. What was in its way moves down; nothing overlaps and no gap is
|
|
1778
|
+
left above a widget.
|
|
1779
|
+
- **Resize** it from its bottom right corner, inside what its kind allows: a tile is 2, 3 or 4 columns wide and always 2 rows
|
|
1780
|
+
tall; the chart over time is 4 to 12 columns by 4 to 10 rows; a breakdown 3 to 12 by 3 to 10; the other charts 4 to 12 by 4
|
|
1781
|
+
to 8; a top list 3 to 6 by 3 to 9; the budgets 4 to 12 by 3 to 10. A row is 56 px, so no chart can be made too small to read.
|
|
1782
|
+
- **Hide** a widget with its ×, and bring it back from **Add widget**, which lists everything that is hidden.
|
|
1783
|
+
- **Duplicate** a chart from its bar (up to four of one kind): two charts over time can sit side by side, one measuring turns by
|
|
1784
|
+
agent and one cost by model. Each copy keeps its own options.
|
|
1785
|
+
- **Undo** takes back the last change (a run of arrow keys on one widget counts as one). **Reset to default** forgets your
|
|
1786
|
+
layout: you see the workspace's default if it has one, else the built-in layout.
|
|
1787
|
+
|
|
1788
|
+
Outside "Edit layout" nothing can be dragged, and until you change something the page is the layout it always was. While you
|
|
1789
|
+
edit, a widget's bar is its heading (its own title row steps aside), and at the default sizes nothing is cut off, editing or not.
|
|
1790
|
+
|
|
1791
|
+
**Heights that follow the content.** A top list, a breakdown and the budgets are as tall as what they hold: a list set to ten
|
|
1792
|
+
rows grows and one set to three shrinks, and the budgets hold a row per project (from six projects on, the list scrolls inside
|
|
1793
|
+
its card). That stops for a widget once you size it by hand: its height is then the one you gave it.
|
|
1794
|
+
|
|
1795
|
+
**With nothing to show yet.** A workspace where no agent has taken a turn in the period shows one plain "No agent turns" state.
|
|
1796
|
+
Someone who has arranged the dashboard, or whose workspace has a default layout, keeps the dashboard instead (a member who has
|
|
1797
|
+
not asked an agent anything yet, for one): each widget says there is nothing yet, and "Edit layout" works as ever.
|
|
1798
|
+
|
|
1799
|
+
**From the keyboard:** while editing, every widget takes the focus (Tab). The arrow keys move it: a column left or right, and
|
|
1800
|
+
up or down past the widget above or below. Shift with an arrow key resizes it by a column or a row. Each change is spoken by a
|
|
1801
|
+
live region ("Turn duration moved to row 3, column 7; 6 wide, 2 tall"), and so is the reason when nothing can change. Tab goes
|
|
1802
|
+
on to the widget's own buttons (options, duplicate, hide). With "reduce motion" set, widgets do not glide to their places.
|
|
1803
|
+
|
|
1804
|
+
**Each widget has options,** behind the "..." button on it (while editing, on its bar). They are saved with that widget, so two
|
|
1805
|
+
copies of a chart differ:
|
|
1806
|
+
|
|
1807
|
+
| Widget | Options |
|
|
1808
|
+
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
1809
|
+
| Usage over time | measure, split, bucket (or automatic), stacked bars, grouped bars or lines, legend on or off, zoom brush on or off |
|
|
1810
|
+
| Breakdown | what to break down by, measure (its own, or the same as the first chart over time), 5, 8, 12 or 20 rows, show shares |
|
|
1811
|
+
| How turns ended | share of turns, or number of turns |
|
|
1812
|
+
| Approvals | stacked, or side by side |
|
|
1813
|
+
| Turn duration | which of the median, 90th, 95th and 99th percentile to draw; a logarithmic axis (off unless you turn it on) |
|
|
1814
|
+
| Top lists | 3, 5 or 10 rows |
|
|
1815
|
+
| Tiles | the trend line, and the line that compares with the period before |
|
|
1816
|
+
| Any chart | chart or table, as what it opens with |
|
|
1817
|
+
|
|
1818
|
+
The switches in a chart's header (measure, split, bucket, chart or table) are the same options: pressing one saves it for that
|
|
1819
|
+
chart. A narrow chart keeps only its title and its options button. The outcomes, approvals and duration charts, and the tiles'
|
|
1820
|
+
trend lines, use the bucket of the first chart over time.
|
|
1821
|
+
|
|
1822
|
+
**Narrower screens** show the same layout on fewer columns, worked out the same way every time: 6 columns below about 840 px
|
|
1823
|
+
of dashboard (tiles three to a row, charts one to a row, lists in pairs) and one column on a phone, in reading order, with the
|
|
1824
|
+
tiles in pairs as before. There you move a widget with the up and down buttons on its bar (or the arrow keys; on 6 columns a
|
|
1825
|
+
drag works too), and nothing is resized. One layout is stored, the 12-column one; a move made on a phone is a move in that
|
|
1826
|
+
layout. On a tablet held sideways the grid is the 12-column one, and a finger on a widget's bar drags it (a finger anywhere else
|
|
1827
|
+
scrolls the page).
|
|
1828
|
+
|
|
1829
|
+
**Saving.** Every change is saved for you, in this workspace, a moment after you make it, with a note that offers Undo. If a
|
|
1830
|
+
save fails the change stays on the page and the page says so, with "Try again"; it is lost only if you leave before it is
|
|
1831
|
+
saved. Your layout is yours: nobody else sees or changes it, on any role.
|
|
1832
|
+
|
|
1833
|
+
**A default for everyone.** An owner can press **Reset > Set as default for everyone**: people who have not arranged the
|
|
1834
|
+
dashboard, and everyone who joins later, start from that layout (their own changes are still their own). "Remove the workspace
|
|
1835
|
+
default" goes back to the built-in layout. Both leave an audit entry (`usage_layout_default_set` with the number of widgets,
|
|
1836
|
+
`usage_layout_default_removed`). The budgets are drawn for admins and owners only, whatever layout says so.
|
|
1837
|
+
|
|
1838
|
+
**What is stored** is JSON, at most 16,000 characters and 40 widgets, checked on the way in and again on the way out
|
|
1839
|
+
(`src/hosted/usage-layout.js`): a widget of a kind this build does not know, a size or a place out of range, a repeated id or a
|
|
1840
|
+
second copy of a tile is dropped, an option that is not one of the listed values falls back to its default, and something that
|
|
1841
|
+
is not a layout at all is refused (400; 413 when too large). Nothing a stored layout says is drawn as it is.
|
|
1842
|
+
|
|
1843
|
+
### Who sees usage
|
|
1844
|
+
|
|
1845
|
+
| Role | Sees |
|
|
1846
|
+
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
|
1847
|
+
| Owner, admin | Every turn in the workspace |
|
|
1848
|
+
| Member | The turns they asked for, and every turn of an agent they connected (it ran on their machine), whoever asked |
|
|
1849
|
+
| Viewer | Nothing (the page says so) |
|
|
1850
|
+
| Share link guests, project tokens, signed-out browsers | Nothing: the usage routes take a signed-in session only |
|
|
1851
|
+
|
|
1852
|
+
The server decides this for every request, including exports, a turn opened by its id, and the lists the filter pickers offer. A
|
|
1853
|
+
member who filters by someone else gets an empty answer, not that person's rows. Another workspace's ids open nothing.
|
|
1854
|
+
|
|
1855
|
+
### The Activity page
|
|
1856
|
+
|
|
1857
|
+
`/w/<workspace>/activity`. What people did, newest first, from the audit log: sign-in and sign-out, passkeys and sessions, members
|
|
1858
|
+
and invites, settings (with the value before and after), projects and pushes, share links and guests, tokens, agents (connected,
|
|
1859
|
+
audience, approval rule, revoked), approval cards (who allowed or denied what), agent work, and exports. Filter by person, kind of
|
|
1860
|
+
action, agent, project, where it came through (a person, a token, a share link guest, the server) and period; search; open an
|
|
1861
|
+
entry for the address and device it came from and exactly what was recorded. "Worth a look" keeps the security-relevant changes:
|
|
1862
|
+
roles, audiences, approval rules, the agent policy, share links switched on, a project made public, tokens made, passkeys
|
|
1863
|
+
removed, and exports.
|
|
1864
|
+
|
|
1865
|
+
- **Owners and admins** read everyone's activity. **Anyone else** in the workspace reads their own, whatever they filter by.
|
|
1866
|
+
- **What someone did in this workspace** (with the address it came from) is the workspace's record, as before.
|
|
1867
|
+
- **Sign-ins, passkey and recovery-code events and the list of signed-in devices are account events.** They belong to the person
|
|
1868
|
+
and cover every workspace that person is in, so by default nobody else sees them: each person sees their own, on their own
|
|
1869
|
+
activity and their own page, and an owner or admin sees none of them for anyone else, in the list, on a person's page or in an
|
|
1870
|
+
export.
|
|
1871
|
+
- **On a server with one team** the operator can switch that on: `shapewall hosted --owners-see-sign-ins` (or
|
|
1872
|
+
`SHAPEWALL_HOSTED_OWNERS_SEE_SIGN_INS=1`). Then a workspace's **owners** (not admins) also see those events and devices for the
|
|
1873
|
+
people who are members of their workspace now, from the day each joined, and the page says so. Do not switch it on where
|
|
1874
|
+
separate teams share a server: a person's sign-in is not tied to one workspace, so an owner would see sign-ins a member made
|
|
1875
|
+
for another team. An entry holds a device label ("Chrome on macOS") and the address the server saw; the device list holds a
|
|
1876
|
+
label and when it was last seen, never an address.
|
|
1877
|
+
- **A person's page** (`/activity/<user id>`; admins, or the person themselves): role and when it changed, what they can reach,
|
|
1878
|
+
the tokens and agents they made, how much they commented, their agent usage and their activity; and, for the person themselves
|
|
1879
|
+
(or an owner where the operator said so), the devices they are signed in on.
|
|
1880
|
+
- **A page is at most 200 entries** however many are asked for; older ones load as you scroll. **A text search always has a
|
|
1881
|
+
start:** without a period it looks at the last 90 days and says so. Searches and filters by agent or project are limited to 60
|
|
1882
|
+
a minute per person.
|
|
1883
|
+
- **Saved views** work here for everyone who has the page, viewers too.
|
|
1884
|
+
- **An agent's page** (`/activity/<agent id>`; admins): what it is, who connected it, who may send it work, its approval rule,
|
|
1885
|
+
its usage and the activity about it.
|
|
1886
|
+
- **Access review** (admins and owners): every person, agent, API token, share link, public project and open invite in one place,
|
|
1887
|
+
with what it reaches, who made it and when it was last used. Anything unused for 90 days is marked. "Export CSV" downloads it
|
|
1888
|
+
(audited as `access_exported`); each list links to the page where access is cut.
|
|
1889
|
+
- **Export CSV** on the log downloads up to 10,000 entries of the filter (audited as `audit_exported`). The older Audit log page
|
|
1890
|
+
and its export are unchanged, and that export now leaves the same audit entry.
|
|
1891
|
+
|
|
1892
|
+
New audit entries in 0.7.0: `signed_out`, `usage_exported`, `audit_exported`, `access_exported`, `usage_retention_changed`,
|
|
1893
|
+
`usage_layout_default_set`, `usage_layout_default_removed`, and
|
|
1894
|
+
`agent_policy_changed` now says which settings changed, from what to what.
|
|
1895
|
+
|
|
1896
|
+
**What the log does and does not prove.** The application has no route that edits or deletes an audit entry; entries are ordered
|
|
1897
|
+
by one increasing id and leave only when the workspace is deleted. That is a record for people who trust the server. It is not
|
|
1898
|
+
tamper-evident: someone with the database file can change it, and there is no hash chain yet. Keep backups if you need to compare.
|
|
1899
|
+
|
|
1900
|
+
### Retention, quota and export
|
|
1901
|
+
|
|
1902
|
+
- **Retention.** Usage records are kept for 400 days by default, and a finished record older than that is removed by the
|
|
1903
|
+
retention job (at start and every 6 hours). A turn still running is never removed. The operator sets it per workspace:
|
|
1904
|
+
`shapewall hosted admin retention ws_ID --usage-days 90` (or `default`). Audit entries are not pruned.
|
|
1905
|
+
- **Quota.** Each usage record counts 400 bytes toward the workspace's storage quota.
|
|
1906
|
+
- **Workspace export.** "Download a copy" now includes `usage.json`: every usage record of the workspace, newest first, read a
|
|
1907
|
+
page at a time (the 50,000 cap is for downloads from the Usage page only).
|
|
1908
|
+
- **A deleted account** takes its saved views with it, in every workspace.
|
|
1909
|
+
|
|
1910
|
+
### The usage and activity API
|
|
1911
|
+
|
|
1912
|
+
For the console (session cookie; every route answers 404 for a workspace you are not in). All of them are one function each in
|
|
1913
|
+
`src/hosted/usage.js` and `src/hosted/activity.js`, so a later admin tool calls the same code.
|
|
1914
|
+
|
|
1915
|
+
`GET /api/workspaces/:ws/usage/summary`, `/usage/series?bucket=day|week|month&groupBy=<dimension>|none&metric=`,
|
|
1916
|
+
`/usage/breakdown?groupBy=`, `/usage/latency?bucket=`, `/usage/top`, `/usage/budgets`, `/usage/options`,
|
|
1917
|
+
`/usage/rows?sort=started|duration|tokens|input|output|cached|cost|steps&dir=asc|desc&cursor=&limit=`, `/usage/rows/:id`,
|
|
1918
|
+
`/usage/export?format=csv|json`. Each takes the filter: `from`, `to` (ISO instants), `tz` (an IANA zone), `agent`, `project`,
|
|
1919
|
+
`person`, `kind`, `outcome` (a comma list or the parameter repeated), `model` (the parameter repeated, once per name, never
|
|
1920
|
+
split: a model's name may hold commas, brackets and spaces), `~` for the empty value, `tokensMin`, `tokensMax`, `durationMin`,
|
|
1921
|
+
`durationMax` (milliseconds), `q`, and `prevFrom` with `prevTo` (the period to compare with; without them, the same span on the
|
|
1922
|
+
wall clock just before). `/usage/breakdown` takes `previous=1` for the same split over that period.
|
|
1923
|
+
|
|
1924
|
+
`GET /api/workspaces/:ws/activity?person=&agent=&project=&group=&action=&source=&sensitive=1&from=&to=&q=&before=&limit=`,
|
|
1925
|
+
`/activity/filters`, `/activity/export`, `/people/:user`, `/agents/:agent/profile`, `/access-review`, `/access-review/export`.
|
|
1926
|
+
`GET|POST /views` and `DELETE /views/:id` keep a person's saved views (`POST` takes `layout` to keep a dashboard layout with a
|
|
1927
|
+
view of the Usage page). `GET /views/:id/layout` answers a view's name and layout to anyone in the workspace who has the Usage
|
|
1928
|
+
page and the view's link (404 for a view that carries none).
|
|
1929
|
+
|
|
1930
|
+
The dashboard's layout: `GET /usage/layout` answers `{ layout, default, canSetDefault }` (the caller's own layout or null, the
|
|
1931
|
+
workspace's default or null), `PUT /usage/layout` with `{ layout }` saves the caller's own, `DELETE /usage/layout` resets it,
|
|
1932
|
+
and `PUT` or `DELETE /usage/layout/default` sets or removes the workspace's default (owners; audited). There is no address for
|
|
1933
|
+
another person's layout. `/usage/top` takes `limit` (1 to 10, default 5); `/usage/latency` answers `p50`, `p90`, `p95` and
|
|
1934
|
+
`p99`. Members and up, like the rest of Usage; in `src/hosted/usage.js` these are `createLayouts` (one function per operation)
|
|
1935
|
+
and `createViews`.
|
|
1936
|
+
|
|
409
1937
|
## Moving to a new origin
|
|
410
1938
|
|
|
411
1939
|
Passkeys belong to a host name (the RP ID), so changing the server's address would lock everyone out. To move:
|
|
@@ -442,6 +1970,16 @@ Old-host passkeys show "For old.example" on the Account page.
|
|
|
442
1970
|
API, signed URLs and tokens.
|
|
443
1971
|
- **CSRF.** Cookie-authenticated writes need JSON and an `Origin` (or `Sec-Fetch-Site: same-origin`) equal to the configured origin,
|
|
444
1972
|
on top of SameSite=Lax. The token API ignores cookies.
|
|
1973
|
+
- **Tailnet identity** (only with `--tailnet-sign-in`). The `Tailscale-User-*` headers are believed only on a request that
|
|
1974
|
+
carries the secret path of the serve entry this server made, on a connection whose other end is owned by root, for an address
|
|
1975
|
+
tailscaled's own whois gives to that login, with exactly one clean login header and no Funnel mark, and never for a request
|
|
1976
|
+
from the server's own machine (any program there can ask tailscaled for the serve address). On direct loopback requests, raw
|
|
1977
|
+
TCP forwards, Funnel traffic and with the flag off they are ignored. The secret is taken off the request before the
|
|
1978
|
+
application sees it and is in no response; a test crawls the hosted server and the local board for it. The server refuses to start with the flag
|
|
1979
|
+
(and suspends it while running) under userspace networking, Tailscale before 1.98, tailscaled's own proxies, in a container,
|
|
1980
|
+
or when the serve config is not its one entry. Root and the Tailscale operator on the machine are trusted; nothing else on
|
|
1981
|
+
the machine or the tailnet is. An identity is per device, not per person
|
|
1982
|
+
([how](#how-the-server-knows-a-request-came-through-tailscale-serve)).
|
|
445
1983
|
- **Rate limits** (in memory, per process): passkey ceremonies 30 a minute per IP; wrong recovery codes 5 per 15 minutes per handle and
|
|
446
1984
|
IP, and 30 an hour per IP (right codes do not count, and nobody can use up another address's attempts); invite lookups 30 a minute
|
|
447
1985
|
per IP; bad tokens 20 a minute per IP; 1200 requests a minute per token; 20 pushes an hour per
|
|
@@ -494,6 +2032,9 @@ server_state; DROP INDEX projects_public_id; ALTER TABLE projects DROP COLUMN pu
|
|
|
494
2032
|
public_at; ALTER TABLE projects DROP COLUMN public_by; ALTER TABLE workspaces DROP COLUMN public_projects; ALTER TABLE passkeys
|
|
495
2033
|
DROP COLUMN rp_id; ALTER TABLE sessions DROP COLUMN admin_seen_at; PRAGMA user_version = 4;`. Do not roll back during an origin
|
|
496
2034
|
move: the old build cannot serve the old address.
|
|
2035
|
+
- **12** (agents, 0.4.0): tables `agents` and `agent_runs`, columns `projects.default_agent_id`, `comments.agent_id` and
|
|
2036
|
+
`agent_claims.agent_id`, and a backfill that turns every token with the `claim` scope into an agent that behaves as before. What a
|
|
2037
|
+
rollback loses is in [Migration 12 and rollback](#migration-12-and-rollback).
|
|
497
2038
|
|
|
498
2039
|
**Why SQLite through `node:sqlite`.** One host, one process, small metadata (images are files), so SQLite fits. `node:sqlite` ships with
|
|
499
2040
|
Node, so the npm package stays free of native addons for the many people who only use the CLI; `better-sqlite3` would download or build a
|
|
@@ -515,6 +2056,8 @@ Try these on the real server, at its real address, before the team depends on it
|
|
|
515
2056
|
re-capture plus push. The local project picker is desktop-only navigation, not a phone hub or a team workspace.
|
|
516
2057
|
4. **Verify the agent boundary.** Use a project-scoped token on the developer machine or CI. Confirm trusted dispatch and shell
|
|
517
2058
|
approval work, imported/guest comments stay inert, and revocation ends access. The hosted server does not run your agent or capture browser.
|
|
2059
|
+
On the project's Agents page, check each agent's audience: a teammate outside it should see the agent greyed on the board with
|
|
2060
|
+
the reason, and a comment sent to one agent should run only on that machine.
|
|
518
2061
|
5. **Check operation and recovery.** Give the server a lifecycle independent of an interactive shell or coding-agent session. The
|
|
519
2062
|
foreground command stops when its process stops; example service/Compose files need deliberate operator setup. Probe `/api/health`
|
|
520
2063
|
from a second device, choose monitoring and backup arrangements, and restore a backup to a separate folder before relying on it.
|
|
@@ -552,13 +2095,14 @@ shapewall hosted --data ./hosted-data --tailscale --tailscale-port 8443 --funnel
|
|
|
552
2095
|
|
|
553
2096
|
These commands change Tailscale Serve/Funnel configuration. Run them only when you intend to expose this server. Install Tailscale,
|
|
554
2097
|
connect the machine, enable MagicDNS and HTTPS certificates, and authorize your unprivileged user as a Tailscale operator first.
|
|
2098
|
+
Add `--tailnet-sign-in` to sign tailnet users in by their tailnet login instead of a passkey ([Tailnet sign-in](#tailnet-sign-in)).
|
|
555
2099
|
The console and passkey origin come from this machine's `*.ts.net` hostname. Do not also pass `--origin` or a non-loopback `--host`.
|
|
556
2100
|
An occupied HTTPS port is refused, including an existing mapping to the same target. SIGINT/SIGTERM removes mappings this process
|
|
557
2101
|
added only while they still match; after a crash inspect `tailscale serve status` and remove the stale mapping explicitly.
|
|
558
2102
|
|
|
559
2103
|
Funnel uses a second loopback listener and a different HTTPS port. It serves guest share pages, guest APIs, signed live HTML,
|
|
560
2104
|
static assets, legal/report routes and health only. Console, sign-in, signup, device login, invitations, member APIs and token APIs
|
|
561
|
-
answer 404. Member session/ceremony cookies are discarded at that listener. Share links still require the secret in the link and
|
|
2105
|
+
answer 404. Member session/ceremony cookies and any `Tailscale-*` header are discarded at that listener. Share links still require the secret in the link and
|
|
562
2106
|
any passcode configured by the workspace. Funnel makes those guest paths public. Ports are not cookie boundaries, so never add
|
|
563
2107
|
member routes to this listener. Tailscale policy/ACL configuration remains the operator's responsibility.
|
|
564
2108
|
|
|
@@ -597,10 +2141,20 @@ shapewall hosted admin export ws_ID --out ./workspace.zip --data ./hosted-data
|
|
|
597
2141
|
shapewall hosted admin reports --data ./hosted-data
|
|
598
2142
|
shapewall hosted admin reports close rp_ID --note "Reviewed" --data ./hosted-data
|
|
599
2143
|
shapewall hosted admin log --data ./hosted-data
|
|
2144
|
+
# An account's passkeys (by handle, or by the tailnet login it is linked to):
|
|
2145
|
+
shapewall hosted admin passkeys list --login ada@example.com --data ./hosted-data
|
|
2146
|
+
shapewall hosted admin passkeys remove PASSKEY_ID --handle ada --data ./hosted-data
|
|
600
2147
|
# Destructive, requires the workspace's exact name:
|
|
601
2148
|
shapewall hosted admin delete ws_ID --confirm "Workspace name" --data ./hosted-data
|
|
602
2149
|
```
|
|
603
2150
|
|
|
2151
|
+
`passkeys remove` is for the case nobody in the product can solve: an account whose only passkey is not its owner's, or is
|
|
2152
|
+
lost with no recovery codes, most of all on a server with tailnet sign-in after a first passkey's 24 hours have passed. Being
|
|
2153
|
+
able to read and write the data folder is the proof, as for every operator command. It removes any passkey, also the last
|
|
2154
|
+
one, and ends the account's passkey sessions (tailnet sessions go on); an account with a tailnet login then signs in through
|
|
2155
|
+
the tailnet and can add a passkey again, and one without signs in with a recovery code if it has one. It is in the operator
|
|
2156
|
+
log and in the account's own security log ("removed by the server's operator").
|
|
2157
|
+
|
|
604
2158
|
Suspension immediately refuses existing API tokens, new device approvals, invitations and guest links. Members can read and export
|
|
605
2159
|
but writes return `workspace_suspended`. Resume restores the previous grants. Operator actions, including listing workspaces/reports and reading the log, are recorded in the
|
|
606
2160
|
operator log; suspension/resume also enter the workspace audit log. The CLI is privileged filesystem access, not a web-admin role.
|
|
@@ -624,7 +2178,8 @@ plus the limits listed above. Run one hosted process per data folder.
|
|
|
624
2178
|
|
|
625
2179
|
## Retention, backup and restore
|
|
626
2180
|
|
|
627
|
-
|
|
2181
|
+
Usage records (one small row per agent turn) are kept for 400 days unless a workspace has its own `--usage-days`; see
|
|
2182
|
+
[Retention, quota and export](#retention-quota-and-export). Current captures stay. By default retention keeps the newest two historical captures per page and viewport plus every historical
|
|
628
2183
|
capture a comment references, open or resolved. Variants are left alone. It runs at start and every 6 hours in-process when the
|
|
629
2184
|
operator starts the hosted server. `--retention-hours 0` disables it; `--retention-keep N` changes the default. To preview or run it:
|
|
630
2185
|
|
|
@@ -633,6 +2188,7 @@ shapewall hosted admin retention --run --dry-run --data ./hosted-data
|
|
|
633
2188
|
shapewall hosted admin retention --run --data ./hosted-data
|
|
634
2189
|
shapewall hosted admin retention ws_ID --keep 4 --data ./hosted-data
|
|
635
2190
|
shapewall hosted admin retention ws_ID --keep default --data ./hosted-data
|
|
2191
|
+
shapewall hosted admin retention ws_ID --usage-days 90 --data ./hosted-data
|
|
636
2192
|
shapewall hosted backup --data ./hosted-data --to ./backups --keep-days 30
|
|
637
2193
|
shapewall hosted restore --from ./backups --check
|
|
638
2194
|
shapewall hosted restore --from ./backups --data ./restored-new-folder
|
|
@@ -668,6 +2224,191 @@ For rollback, prefer the pre-upgrade backup in a fresh data folder and the previ
|
|
|
668
2224
|
on the new database ignores additive columns but also removes suspension enforcement: keep affected workspaces blocked externally
|
|
669
2225
|
until upgraded again. Do not drop the operator log or reset the ledger casually. Test rollback on a copy first.
|
|
670
2226
|
|
|
2227
|
+
### Migration 12 and rollback
|
|
2228
|
+
|
|
2229
|
+
Migration 12 (0.4.0) makes agents first-class ([Agents on a hosted board](#agents-on-a-hosted-board)). It is additive and runs once:
|
|
2230
|
+
|
|
2231
|
+
- tables `agents` (one row per token with the `claim` scope: kind, icon, tint, machine label, audience, approval rule and its two
|
|
2232
|
+
roles, who created it, when it was last seen) and `agent_runs` (the usage record of each comment an agent took);
|
|
2233
|
+
- columns `projects.default_agent_id`, `comments.agent_id` (the agent a comment was sent to; empty means any agent) and
|
|
2234
|
+
`agent_claims.agent_id`;
|
|
2235
|
+
- a backfill: every token that already has the `claim` scope becomes an agent of kind "watcher" with the audience "everyone the
|
|
2236
|
+
agent policy trusts", which is what it did before. Open claims are linked to their agent. No project gets a default agent and no
|
|
2237
|
+
comment gets an address, so every comment stays open to any agent, as before.
|
|
2238
|
+
|
|
2239
|
+
A token with the `claim` scope that has no agent row (made while an older build ran on the upgraded database) becomes an agent the
|
|
2240
|
+
first time it calls the server, with the same audience. Back up before upgrading.
|
|
2241
|
+
|
|
2242
|
+
For rollback, prefer the pre-upgrade backup in a fresh data folder with the previous release. Running 0.3.4 on the upgraded database
|
|
2243
|
+
also works, since it ignores the new tables and columns, but it loses what they held:
|
|
2244
|
+
|
|
2245
|
+
- **Routing.** A comment sent to one agent can be taken by any watcher, and an agent takes work from everyone the agent policy
|
|
2246
|
+
trusts, whatever audience it was given. Tighten the project's Agent policy first if that matters.
|
|
2247
|
+
- **Agents made after the upgrade** (audience "only the person who connected it") behave like every other token there.
|
|
2248
|
+
- Default agents, icons, audiences, approval roles and usage records are not shown, and are still there when you upgrade again.
|
|
2249
|
+
|
|
2250
|
+
To remove the schema as well (SQLite 3.35+), with the server stopped: `DROP TABLE agent_runs; DROP TABLE agents; ALTER TABLE projects
|
|
2251
|
+
DROP COLUMN default_agent_id; ALTER TABLE comments DROP COLUMN agent_id; ALTER TABLE agent_claims DROP COLUMN agent_id; DELETE FROM
|
|
2252
|
+
schema_migrations WHERE version = 12; PRAGMA user_version = 11;`. The next upgrade then backfills again from the tokens. Never reset
|
|
2253
|
+
the ledger any other way. Test a rollback on a copy first.
|
|
2254
|
+
|
|
2255
|
+
### Migration 13 and rollback
|
|
2256
|
+
|
|
2257
|
+
Migration 13 (0.5.0) adds chat with [connected agents](#connected-agents). It is additive and runs once:
|
|
2258
|
+
|
|
2259
|
+
- tables `chat_threads` (a thread of a board, the agent it talks to, and for a private chat its owner), `chat_messages` (the
|
|
2260
|
+
person's messages and the agent's answers) and `chat_turns` (one question on its way through an agent, and how it ended);
|
|
2261
|
+
- column `device_logins.meta` (what a machine that asks to connect says it runs, for the approval page).
|
|
2262
|
+
|
|
2263
|
+
Nothing existing is rewritten: no token gains a scope, no agent changes its audience, and `watch --remote` and `mcp --remote` work
|
|
2264
|
+
with the same tokens. The usage records of chat turns go in `agent_runs`, the table migration 12 made. Back up before upgrading.
|
|
2265
|
+
|
|
2266
|
+
For rollback, prefer the pre-upgrade backup in a fresh data folder with the previous release. Running 0.4.0 on the upgraded database
|
|
2267
|
+
also works, since it ignores the new tables, but:
|
|
2268
|
+
|
|
2269
|
+
- **Chat is gone from the board**, and the threads are not shown. They are still there when you upgrade again.
|
|
2270
|
+
- **Connected agents show as ordinary agents** with no chat. Their tokens keep working on the token API, so a comment sent to one
|
|
2271
|
+
can still be read and answered through it; 0.4.0 shows the `agent` scope on such a token and gives it no meaning.
|
|
2272
|
+
Revoke the connected agents first if that is not what you want.
|
|
2273
|
+
- A machine still running `shapewall agent connect` gets 404 from the link routes and keeps retrying. Stop it.
|
|
2274
|
+
|
|
2275
|
+
To remove the schema as well (SQLite 3.35+), with the server stopped: `DROP TABLE chat_turns; DROP TABLE chat_messages; DROP TABLE
|
|
2276
|
+
chat_threads; ALTER TABLE device_logins DROP COLUMN meta; DELETE FROM schema_migrations WHERE version = 13; PRAGMA user_version =
|
|
2277
|
+
12;`. Never reset the ledger any other way. Test a rollback on a copy first.
|
|
2278
|
+
|
|
2279
|
+
### Migration 14 and rollback
|
|
2280
|
+
|
|
2281
|
+
Migration 14 (0.6.0) adds approvals and edits from a hosted board
|
|
2282
|
+
([Edits from the board](#edits-from-the-board-the-trust-decision)). It is additive and runs once:
|
|
2283
|
+
|
|
2284
|
+
- table `chat_permissions` (one row per permission card a connected agent asked during a fix: what it asked, as hashed, its
|
|
2285
|
+
state, who answered and when);
|
|
2286
|
+
- columns `agent_runs.approvals_asked`, `agent_runs.approvals_allowed` and `agent_runs.approvals_denied` (how many requests a
|
|
2287
|
+
fix asked and how they ended).
|
|
2288
|
+
|
|
2289
|
+
Nothing existing is rewritten: no token gains a scope, no agent changes its audience or its approval rule, and a connected agent
|
|
2290
|
+
reads and answers only until its own machine says more. `watch --remote` and `mcp --remote` work with the same tokens. Back up
|
|
2291
|
+
before upgrading.
|
|
2292
|
+
|
|
2293
|
+
For rollback, prefer the pre-upgrade backup in a fresh data folder with the previous release. Running 0.5.0 on the upgraded
|
|
2294
|
+
database also works, since it ignores the new table and columns, but:
|
|
2295
|
+
|
|
2296
|
+
- **A fix cannot be started.** 0.5.0 has no Fix with an agent on hosted comments and relays no cards. Connected agents chat and
|
|
2297
|
+
answer comments as they did in 0.5.0.
|
|
2298
|
+
- **Cards and their answers are not shown.** They are still there when you upgrade again, and the audit entries stay in the
|
|
2299
|
+
audit log.
|
|
2300
|
+
- **A machine started with `--approvals`** keeps its own setting in its policy file. It takes no edits while the server is
|
|
2301
|
+
0.5.0, because that server never asks for a fix.
|
|
2302
|
+
|
|
2303
|
+
To remove the schema as well (SQLite 3.35+), with the server stopped: `DROP TABLE chat_permissions; ALTER TABLE agent_runs DROP
|
|
2304
|
+
COLUMN approvals_asked; ALTER TABLE agent_runs DROP COLUMN approvals_allowed; ALTER TABLE agent_runs DROP COLUMN
|
|
2305
|
+
approvals_denied; DELETE FROM schema_migrations WHERE version = 14; PRAGMA user_version = 13;`. Never reset the ledger any other
|
|
2306
|
+
way. Test a rollback on a copy first.
|
|
2307
|
+
|
|
2308
|
+
### Migration 15 and rollback
|
|
2309
|
+
|
|
2310
|
+
Migration 15 (0.7.0) adds what the Usage and Activity pages need ([Usage and activity](#usage-and-activity)). It is additive
|
|
2311
|
+
and runs once:
|
|
2312
|
+
|
|
2313
|
+
- columns on `agent_runs`: `agent_owner` (who connected the agent; filled in for existing rows), `duration_ms` (filled in for
|
|
2314
|
+
finished rows from their start and end), `agent_ms`, `tools`, `approvals_auto`, `approvals_by`, `window_used`, `window_size`;
|
|
2315
|
+
- indexes `agent_runs_owner` and `agent_runs_thread`;
|
|
2316
|
+
- table `saved_views` (a person's named filters on the Usage and Activity pages);
|
|
2317
|
+
- column `workspaces.retention_usage_days` (how long a workspace keeps usage records; empty means the default, 400 days);
|
|
2318
|
+
- indexes on the audit log for the Activity filters: `audit_workspace_at`, `audit_workspace_user`, `audit_account_user`.
|
|
2319
|
+
|
|
2320
|
+
Nothing existing is rewritten beyond the two fill-ins above, and no role gains a permission it did not have, except that members
|
|
2321
|
+
may now read their own usage and everyone their own activity. Back up before upgrading. From 0.7.0 the retention job removes
|
|
2322
|
+
finished usage records older than 400 days; set `--usage-days` for a workspace first if you want to keep them longer.
|
|
2323
|
+
|
|
2324
|
+
For rollback, prefer the pre-upgrade backup in a fresh data folder with the previous release. Running 0.6.0 on the upgraded
|
|
2325
|
+
database also works, since it ignores the new columns, table and indexes, but:
|
|
2326
|
+
|
|
2327
|
+
- **There are no Usage and Activity pages,** and turns recorded by 0.6.0 lack the new fields (they show as "not reported" after
|
|
2328
|
+
upgrading again, and their duration is not filled in).
|
|
2329
|
+
- **Usage records are not pruned** and do not count toward the quota while 0.6.0 runs.
|
|
2330
|
+
- **Saved views stay** in their table, unused.
|
|
2331
|
+
|
|
2332
|
+
To remove the schema as well (SQLite 3.35+), with the server stopped: `DROP TABLE saved_views; DROP INDEX agent_runs_owner; DROP
|
|
2333
|
+
INDEX agent_runs_thread; DROP INDEX audit_workspace_at; DROP INDEX audit_workspace_user; DROP INDEX audit_account_user; ALTER
|
|
2334
|
+
TABLE agent_runs DROP COLUMN agent_owner; ALTER TABLE agent_runs DROP COLUMN duration_ms; ALTER TABLE agent_runs DROP COLUMN
|
|
2335
|
+
agent_ms; ALTER TABLE agent_runs DROP COLUMN tools; ALTER TABLE agent_runs DROP COLUMN approvals_auto; ALTER TABLE agent_runs
|
|
2336
|
+
DROP COLUMN approvals_by; ALTER TABLE agent_runs DROP COLUMN window_used; ALTER TABLE agent_runs DROP COLUMN window_size; ALTER
|
|
2337
|
+
TABLE workspaces DROP COLUMN retention_usage_days; DELETE FROM schema_migrations WHERE version = 15; PRAGMA user_version = 14;`.
|
|
2338
|
+
Never reset the ledger any other way. Test a rollback on a copy first.
|
|
2339
|
+
|
|
2340
|
+
### Migration 16 and rollback
|
|
2341
|
+
|
|
2342
|
+
Migration 16 (0.7.0) adds one table and changes nothing else:
|
|
2343
|
+
|
|
2344
|
+
- table `usage_layouts`: the layouts of the Usage dashboard ([Arranging the dashboard](#arranging-the-dashboard)). One row per
|
|
2345
|
+
layout: a person's own (`kind` `person`, `subject` their user id), the workspace's default (`default`, empty subject), and the
|
|
2346
|
+
layout a saved view carries (`view`, the view's id). `layout` is the checked JSON; `updated_by` and `updated_at` say who saved
|
|
2347
|
+
it and when. Rows go with their workspace, with a member who leaves or is removed, with a deleted account, and with a deleted
|
|
2348
|
+
view.
|
|
2349
|
+
|
|
2350
|
+
It is additive, and it does not touch `saved_views` or any other table of migration 15. Back up before upgrading.
|
|
2351
|
+
|
|
2352
|
+
For rollback, prefer the pre-upgrade backup in a fresh data folder with the previous build. Running a build without migration 16
|
|
2353
|
+
on the upgraded database also works, since it ignores the table, but:
|
|
2354
|
+
|
|
2355
|
+
- **Everyone sees the built-in dashboard,** fixed as it was. Layouts, the workspace's default and the layouts of saved views
|
|
2356
|
+
stay in the table, unused, and are back when you upgrade again.
|
|
2357
|
+
- **Saved views keep working** as names for an address. A link that names a view (`view=`) opens the filters and ignores the
|
|
2358
|
+
rest.
|
|
2359
|
+
- **A member removed or an account deleted meanwhile** leaves their rows behind. They are harmless (a layout holds no usage
|
|
2360
|
+
data, only which widgets go where), and `DELETE FROM usage_layouts WHERE kind = 'person' AND subject NOT IN (SELECT user_id
|
|
2361
|
+
FROM memberships WHERE workspace_id = usage_layouts.workspace_id);` clears them.
|
|
2362
|
+
|
|
2363
|
+
To remove the schema as well, with the server stopped: `DROP TABLE usage_layouts; DELETE FROM schema_migrations WHERE version =
|
|
2364
|
+
16;`, then set `PRAGMA user_version` to the highest version left in `schema_migrations` (17 where migration 17 is there, else
|
|
2365
|
+
15). Never reset the ledger any other way. Test a rollback on a copy first.
|
|
2366
|
+
|
|
2367
|
+
### Migration 17 and rollback
|
|
2368
|
+
|
|
2369
|
+
Migration 17 (0.7.0) adds what the passkey settings and tailnet sign-in need ([Signing in](#signing-in)). It is additive and
|
|
2370
|
+
runs once:
|
|
2371
|
+
|
|
2372
|
+
- column `workspaces.step_up` (the "Ask for a passkey again" settings as JSON; `{}` is all off);
|
|
2373
|
+
- columns `users.tailnet_login`, `users.tailnet_linked_at` and `users.tailnet_user_id` (Tailscale's id of the linked user), with
|
|
2374
|
+
the unique index `users_tailnet_login`;
|
|
2375
|
+
- column `passkeys.tailnet_added_from` (the device a first passkey was added from in a tailnet session);
|
|
2376
|
+
- table `server_settings` (what the operator switched for the whole server: passkeys on a tailnet sign-in server);
|
|
2377
|
+
- column `sessions.tailnet_login` (set on a session that came in by tailnet identity);
|
|
2378
|
+
- column `invites.tailnet_login` (an invite for one login);
|
|
2379
|
+
- table `tailnet_visitors` (logins that arrived and are in no workspace).
|
|
2380
|
+
|
|
2381
|
+
**What changes on upgrade, with no setting touched:** the passkey prompts before workspace actions are gone. A signed-in session
|
|
2382
|
+
with the right role is enough. If you want them back, an owner switches the groups on in Settings, per workspace.
|
|
2383
|
+
|
|
2384
|
+
For rollback, prefer the pre-upgrade backup in a fresh data folder with the previous release. Running the previous build on the
|
|
2385
|
+
upgraded database also works, but:
|
|
2386
|
+
|
|
2387
|
+
- **The old passkey rules are back for everyone,** whatever the workspaces chose.
|
|
2388
|
+
- **Delete tailnet sessions** (`DELETE FROM sessions WHERE tailnet_login IS NOT NULL;`). An older build cannot use them in any
|
|
2389
|
+
case: they are stored under the hash of `tailnet:<token>`, and an older build looks a cookie up by the hash of the token
|
|
2390
|
+
alone, so it finds nothing. Deleting them is tidiness, and the documented step.
|
|
2391
|
+
- **Accounts made by tailnet sign-in have no passkey** and no recovery codes, so they cannot sign in to an older build.
|
|
2392
|
+
- **Invites made for a tailnet login** work for anyone who has their link on an older build. Revoke the pending ones first.
|
|
2393
|
+
|
|
2394
|
+
To remove the schema as well (SQLite 3.35+), with the server stopped: `DROP TABLE tailnet_visitors; DROP INDEX
|
|
2395
|
+
users_tailnet_login; ALTER TABLE users DROP COLUMN tailnet_login; ALTER TABLE users DROP COLUMN tailnet_linked_at; ALTER TABLE
|
|
2396
|
+
users DROP COLUMN tailnet_user_id; ALTER TABLE passkeys DROP COLUMN tailnet_added_from; DROP TABLE server_settings; ALTER TABLE
|
|
2397
|
+
sessions DROP COLUMN tailnet_login; ALTER TABLE invites DROP COLUMN tailnet_login; ALTER TABLE workspaces DROP COLUMN step_up;
|
|
2398
|
+
DELETE FROM schema_migrations WHERE version = 17;`, then set `PRAGMA user_version` to the highest version left in
|
|
2399
|
+
`schema_migrations` (16 where the saved Usage layouts are there, else 15).
|
|
2400
|
+
|
|
2401
|
+
**A database from a build of this release before it was released.** While 0.7.0 was being made, the sign-in migration was
|
|
2402
|
+
numbered 16 for a while. A database such a build opened says "16 ran" in its ledger, which now means the Usage layouts. The
|
|
2403
|
+
server recognises it (the sign-in tables are there, `usage_layouts` is not, 17 is not marked), adds what that early build
|
|
2404
|
+
did not have yet, and corrects the ledger to "17 ran, 16 did not", so both end applied once. Nothing to do by hand.
|
|
2405
|
+
|
|
2406
|
+
**Migrations 16 and 17.** Number 16 is the Usage layouts (table `usage_layouts`) and 17 is sign-in; they were made separately
|
|
2407
|
+
and do not depend on each other. The server keeps a ledger of what ran (`schema_migrations`), so they can reach a database in
|
|
2408
|
+
either order: a database that ran only 16 runs 17 on the next start, and one that ran only 17 runs 16. `PRAGMA user_version` is
|
|
2409
|
+
the highest number applied, not a count. Rolling one back does not touch the other; remove only its own row from
|
|
2410
|
+
`schema_migrations`.
|
|
2411
|
+
|
|
671
2412
|
## Secrets, logs and legal review
|
|
672
2413
|
|
|
673
2414
|
`SHAPEWALL_HOSTED_SECRET_FILE` and `RESEND_API_KEY_FILE` read private secret files. systemd `LoadCredential=shapewall-secret:...` and
|
|
@@ -687,13 +2428,15 @@ The server never runs a model or an agent process. Capture and execution stay
|
|
|
687
2428
|
on the developer's machine or CI. In a project's console, **Agent policy**
|
|
688
2429
|
sets trusted workspace roles or handles, board overrides, `onlyMentions`,
|
|
689
2430
|
claims per UTC day (50 by default), and open claims (3 by default). Zero stops
|
|
690
|
-
new claims.
|
|
2431
|
+
new claims. Removed members and changed
|
|
691
2432
|
trust policy invalidate vouches immediately.
|
|
692
2433
|
|
|
693
2434
|
Use project tokens with `read, reply, status, claim` for runners. `reply` posts
|
|
694
2435
|
agent replies, `status` changes their status, and `claim` takes dispatched work.
|
|
695
2436
|
`resolve` separately allows resolving/reopening; `push` uploads captures;
|
|
696
|
-
`import` is reserved for the local-to-shared bridge
|
|
2437
|
+
`import` is reserved for the local-to-shared bridge; `agent` is the link of a
|
|
2438
|
+
[connected agent](#connected-agents), granted only by approving
|
|
2439
|
+
`shapewall agent connect`. Old `comment` tokens map
|
|
697
2440
|
to `reply,status`, without acquiring `claim`. Give CI only `push` when it does
|
|
698
2441
|
not need to read the project.
|
|
699
2442
|
|
|
@@ -703,19 +2446,30 @@ vouches for the exact current text and anchor. Editing clears it, and both
|
|
|
703
2446
|
after you opened it: reload and read it again. Only admins set an agent status
|
|
704
2447
|
from the board. Approvals and denials of an agent's commands are in the audit
|
|
705
2448
|
log. Non-admin
|
|
706
|
-
requests need **Approve agent run
|
|
2449
|
+
requests need **Approve agent run** by a trusted admin, by
|
|
707
2450
|
default. Guest and agent-written comments can never be dispatched, including
|
|
708
2451
|
with `--include-guests`. Imported comments start inert and need an explicit
|
|
709
2452
|
trusted vouch. Claim tokens see only dispatched comments, including direct-id
|
|
710
2453
|
reads; guest replies are removed from their responses. Read tokens without
|
|
711
2454
|
`claim` may inspect untrusted comments with the existing guest opt-in.
|
|
712
2455
|
|
|
2456
|
+
A claim token is an agent ([Agents on a hosted board](#agents-on-a-hosted-board)), and two more rules apply to it on every route:
|
|
2457
|
+
it sees and takes only comments sent to it or to any agent, and only when the person whose approval stands on the comment is in its
|
|
2458
|
+
audience. A comment sent to another agent answers 404 `unknown_comment`, exactly like one that was never dispatched: lists, direct
|
|
2459
|
+
reads, replies, statuses, approvals, comment files and the MCP tools. The events stream still carries ids only. On a comment it
|
|
2460
|
+
may work on, it reads only the replies of people in its audience. The token that holds a comment keeps all of this for that comment
|
|
2461
|
+
until it finishes.
|
|
2462
|
+
|
|
2463
|
+
**Tokens without `claim` are not agents and are not routed.** A token with `read` (and `reply` or `status`) but no `claim` sees every
|
|
2464
|
+
comment of the project, including the ones sent to one agent, exactly as before 0.4.0: it is for scripts, CI and reporting, cannot take
|
|
2465
|
+
work, and is not listed on the board. Give `claim` to what should behave as an agent, and leave it off anything that only needs to read.
|
|
2466
|
+
|
|
713
2467
|
Claims use an atomic per-project budget and compare-and-set. Exceeding a budget
|
|
714
2468
|
returns HTTP 429 `agent_budget`; another token cannot take over a live claim.
|
|
715
2469
|
An operator suspension, token revocation, membership loss, changed trust or an
|
|
716
2470
|
edited comment prevents subsequent requests. Shell approvals bind one exact
|
|
717
2471
|
command and one claim generation, expire after two minutes and need a trusted
|
|
718
|
-
admin
|
|
2472
|
+
admin (and their passkey again when the workspace asks for it). They cannot be reused on a later run of identical text.
|
|
719
2473
|
|
|
720
2474
|
`shapewall watch --remote` uses bearer-authenticated SSE at `/api/v1/events`,
|
|
721
2475
|
with bounded polling fallback when a proxy does not support streams. Events
|