@factiii/runner 0.27.0 → 0.43.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/DISCLOSURE +174 -0
- package/README.md +36 -16
- package/dist/cli.js +73257 -39541
- package/dist/vault-client.js +876 -0
- package/dist/vault-db.js +858 -0
- package/embedder/app.py +331 -0
- package/embedder/clip_tokenizer.py +137 -0
- package/embedder/convert_clip.py +119 -0
- package/embedder/convert_onnx.py +129 -0
- package/embedder/convert_text.py +148 -0
- package/embedder/onnx_backend.py +48 -0
- package/embedder/overrides-onnx.txt +3 -0
- package/embedder/requirements-onnx.txt +22 -0
- package/embedder/requirements.txt +20 -0
- package/embedder/serve.py +241 -0
- package/embedder/text_tokenizer.py +34 -0
- package/native/simhid.m +7 -0
- package/native/simstream.m +7 -0
- package/package.json +26 -14
- package/plugin/factiii/bin/factiii-board-mcp +11 -3
- package/plugin/factiii/bin/factiii-secrets +88 -21
- package/plugin/factiii/bin/session-context.sh +55 -2
- package/plugin/factiii/skills/board-sessions/SKILL.md +74 -0
- package/plugin/factiii/skills/factiii-secrets/SKILL.md +12 -3
- package/plugin/factiii/skills/runner-onboarding/SKILL.md +67 -0
- package/plugin/factiii/skills/scratchpad/SKILL.md +1 -0
- package/plugin/factiii/skills/share-a-port/SKILL.md +11 -6
- package/index/image-package.json +0 -8
- package/index/index.js +0 -105575
- package/native/screenhost.m +0 -500
- package/vendor/frpc-darwin-amd64 +0 -0
- package/vendor/frpc-darwin-arm64 +0 -0
- package/vendor/frpc-linux-amd64 +0 -0
- package/vendor/frpc-linux-arm64 +0 -0
package/DISCLOSURE
ADDED
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
@factiii/runner: dual-use disclosure
|
|
2
|
+
|
|
3
|
+
WHAT THIS PACKAGE IS
|
|
4
|
+
|
|
5
|
+
Factiii Runner lets a person run AI coding agents (Claude Code and similar)
|
|
6
|
+
on a computer they own, and drive them from the Factiii web, desktop and
|
|
7
|
+
mobile apps (https://factiii.com). The owner installs it on their own machine
|
|
8
|
+
and pairs it with their own Factiii account. It then accepts work only from
|
|
9
|
+
that account and from board members the owner has approved.
|
|
10
|
+
|
|
11
|
+
Doing that job means the runner can do things that malware also does. Each
|
|
12
|
+
one is listed below with why it is there and how the owner controls it.
|
|
13
|
+
Nothing here runs at install: the package has no install scripts.
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
CAPABILITIES THAT RESEMBLE MALWARE
|
|
17
|
+
|
|
18
|
+
1. Remote shell and command execution
|
|
19
|
+
The runner starts terminal sessions (tmux) and agent processes on the
|
|
20
|
+
machine and streams them to the owner's Factiii app over WebRTC. That is
|
|
21
|
+
the product: the owner, or an approved board member, types into a
|
|
22
|
+
terminal on their own computer from a phone or browser. Some processes
|
|
23
|
+
are spawned detached so that a running agent survives a runner restart.
|
|
24
|
+
|
|
25
|
+
2. iOS Simulator viewing and input (macOS)
|
|
26
|
+
native/simhid.m and native/simstream.m are built on the owner's Mac and
|
|
27
|
+
stream the iOS Simulator's video and send it touch input, for testing
|
|
28
|
+
mobile apps. They reach the Simulator only, never the Mac's own screen,
|
|
29
|
+
mouse or keyboard. The runner does not capture or control the Mac's
|
|
30
|
+
desktop; to see it remotely the owner uses macOS Screen Sharing (VNC)
|
|
31
|
+
over their own Tailscale network, which the runner neither installs nor
|
|
32
|
+
starts.
|
|
33
|
+
|
|
34
|
+
3. Reverse tunnels (frpc, downloaded on first use)
|
|
35
|
+
The package does not contain the frp client (https://github.com/fatedier/frp).
|
|
36
|
+
The first time the owner or an agent shares a local dev server as a
|
|
37
|
+
preview link (`factiii-expose`), the runner downloads frp's official
|
|
38
|
+
release from GitHub, checks its SHA-256 against the value frp publishes
|
|
39
|
+
(pinned in the runner's source), and refuses it if they differ. A runner
|
|
40
|
+
that never shares a port never has frpc. Tunnels go only to Factiii's own
|
|
41
|
+
tunnel server, each with a tunnel-only credential (7 days, renewed daily
|
|
42
|
+
while the tunnel runs) that nothing else on the server accepts; the
|
|
43
|
+
runner's access token never reaches frpc. A tunnel keeps running after
|
|
44
|
+
the session that opened it ends, until it is stopped. Each tunnel is
|
|
45
|
+
listed in the app and can be stopped.
|
|
46
|
+
|
|
47
|
+
4. Starting at login (persistence)
|
|
48
|
+
Off by default. Only the person at the machine turns it on, in its own
|
|
49
|
+
terminal: by answering yes to setup's "Start this runner at login? [y/N]"
|
|
50
|
+
(Enter alone means no), or by running `factiii-runner service install`.
|
|
51
|
+
Either installs one per-user login service (a LaunchAgent on macOS, a
|
|
52
|
+
systemd user unit on Linux, a scheduled task on Windows), so the runner is
|
|
53
|
+
available after a reboot. The app and the account can see it and turn it
|
|
54
|
+
off, never on: a request to install it from anywhere but that terminal is
|
|
55
|
+
refused. `factiii-runner service remove` deletes it.
|
|
56
|
+
The runner lists the LaunchAgents folder to find and manage its own
|
|
57
|
+
entries, and reads the owner's other agents there only to name the
|
|
58
|
+
services in item 10. It never adds, changes or removes another agent.
|
|
59
|
+
|
|
60
|
+
5. Credentials and secrets
|
|
61
|
+
- The runner's connection token is stored encrypted, under a key kept in
|
|
62
|
+
the OS keychain (macOS Keychain via `security`, libsecret on Linux,
|
|
63
|
+
DPAPI on Windows).
|
|
64
|
+
- The owner can keep deploy secrets in a local, encrypted store. They are
|
|
65
|
+
handed to commands only through named jobs the owner defines, and each
|
|
66
|
+
use is recorded in an audit log the owner can read.
|
|
67
|
+
- The runner reads environment variables it is configured with (for
|
|
68
|
+
example FACTIII_* settings). It never reads `.env` files, SSH keys,
|
|
69
|
+
browser data, wallets or other programs' credentials. A test in this
|
|
70
|
+
package (src/packageContents.test.ts) fails if bundled code opens a
|
|
71
|
+
.env file.
|
|
72
|
+
|
|
73
|
+
6. System and remote-access inspection
|
|
74
|
+
Runner > Status, and "Ready to be a server" in Factiii Desktop, show the
|
|
75
|
+
owner whether their machine can serve as an always-on host. To do this the
|
|
76
|
+
runner reads disk and memory use (/proc/meminfo on Linux), power settings
|
|
77
|
+
(`pmset -g`), screen-lock and FileVault state (`sysadminctl`, `ioreg`),
|
|
78
|
+
whether Screen Sharing is on (a local check of port 5900), and the
|
|
79
|
+
machine's Tailscale address (`ifconfig`, `tailscale status`). These
|
|
80
|
+
results go to the owner's own app.
|
|
81
|
+
- The runner never changes these settings itself. Where a setting needs
|
|
82
|
+
changing it shows the command, such as `sudo pmset ...`, for the owner
|
|
83
|
+
to run, or the owner runs it from Factiii Desktop with their password.
|
|
84
|
+
- "Keep awake" holds `caffeinate` while the owner asks for it.
|
|
85
|
+
- The runner never installs or starts Tailscale. It only reads its status.
|
|
86
|
+
|
|
87
|
+
7. Heartbeat to a status page (opt-in)
|
|
88
|
+
If the owner runs `factiii-runner status-page set` with a token for their
|
|
89
|
+
own status page, the runner sends a periodic heartbeat to it: its name,
|
|
90
|
+
version and time, plus this machine's Tailscale name, address and user.
|
|
91
|
+
That page shows the Tailscale details only on its access-controlled admin
|
|
92
|
+
view, as the owner's way back in when Factiii itself is down. This is off
|
|
93
|
+
unless the owner turns it on.
|
|
94
|
+
|
|
95
|
+
8. Updating itself
|
|
96
|
+
The runner checks npm and its GitHub Releases (github.com/factiii/runner)
|
|
97
|
+
for a newer @factiii/runner. By default it installs one by itself when
|
|
98
|
+
nothing is running, about every 6 hours; "factiii-runner update auto off"
|
|
99
|
+
turns that off, and then it installs only after a person clicks "Approve
|
|
100
|
+
update" in the Factiii app. It installs only a version newer than the one
|
|
101
|
+
running, only from the npm registry or a GitHub Release tarball that
|
|
102
|
+
matches its published SHA-256 and carries a valid signature (its .sig)
|
|
103
|
+
by Factiii's release key, an Ed25519 public key built into the runner
|
|
104
|
+
(src/releaseKey.ts). A GitHub Release with no signature, or one that
|
|
105
|
+
does not verify, is refused, so whoever can publish a release on that
|
|
106
|
+
repository still cannot make a runner install it without the key. From
|
|
107
|
+
npm it installs only what npm serves: each version is published from
|
|
108
|
+
Factiii's release workflow over npm's trusted publishing, and goes live
|
|
109
|
+
only when the owner approves it with two-factor authentication. Before
|
|
110
|
+
installing it keeps a copy of the
|
|
111
|
+
running version, and if the new one fails to start it puts that copy
|
|
112
|
+
back and does not install the failed version by itself again.
|
|
113
|
+
|
|
114
|
+
9. Other downloads
|
|
115
|
+
On request, the runner installs developer tools the owner asks for: the
|
|
116
|
+
AI agent CLIs, Python packages for the local embedder (embedder/), and
|
|
117
|
+
Tart (a pinned release that the runner verifies is signed by Cirrus Labs
|
|
118
|
+
before installing it).
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
10. Connections, running services and their logs (owner only)
|
|
122
|
+
Runner > Remote connections shows the runner's owner who is connected
|
|
123
|
+
(each link's account, transport, start time and open terminals) and what
|
|
124
|
+
the machine is serving: containers (`docker ps`), pm2 processes
|
|
125
|
+
(`pm2 jlist`), the user's LaunchAgents (`launchctl list`, and each one's
|
|
126
|
+
plist to see what it runs), listening ports (`lsof`) and the local
|
|
127
|
+
embedder's health. On request it shows the last lines of one of those
|
|
128
|
+
services' logs (`pm2 logs`, `docker logs`, or the log file a LaunchAgent
|
|
129
|
+
names), at most 2,000 lines. All of it is read-only, answered only to the
|
|
130
|
+
owner over their own link, and never sent to the Factiii server.
|
|
131
|
+
|
|
132
|
+
11. Who can connect, how long access lasts, and how to stop it
|
|
133
|
+
Who: a link opens only for the owner and for board members the owner
|
|
134
|
+
gave an access level, on a board the owner has joined. The server names
|
|
135
|
+
who is connecting and their boards, and the runner checks its own grant
|
|
136
|
+
for that person; if either is missing, the link is refused. Lowering a
|
|
137
|
+
member's level closes their terminals and video at once. Setting them to
|
|
138
|
+
None on every board closes their link. A card AI session or a job they
|
|
139
|
+
already started keeps running until the owner ends it.
|
|
140
|
+
How long: the runner's access token expires after at most 30 days (7
|
|
141
|
+
for a current runner once it has renewed) and is renewed daily. Its refresh token changes on every use and stops working
|
|
142
|
+
after 90 days unused. If an old refresh token is reused, the server
|
|
143
|
+
ends the pairing, cuts live connections and alerts the owner. Terminal
|
|
144
|
+
sessions have no idle timeout: they run until someone ends them from
|
|
145
|
+
the app, or until the runner stops.
|
|
146
|
+
How to stop it:
|
|
147
|
+
- Stop the `factiii-runner start` process (Ctrl-C, or end the process).
|
|
148
|
+
Nothing restarts it unless the owner installed the login service
|
|
149
|
+
(item 4).
|
|
150
|
+
- `factiii-runner service remove` removes the login service.
|
|
151
|
+
- "Disconnect" under Settings > Runners in the Factiii app revokes the
|
|
152
|
+
runner on the server, which checks this at every connection. The
|
|
153
|
+
runner is told to stop its jobs and delete their containers.
|
|
154
|
+
- `factiii-runner nuke` erases everything the runner holds, secrets
|
|
155
|
+
included, and unpairs it.
|
|
156
|
+
- `npm uninstall -g @factiii/runner` removes the package.
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
WHAT IT DOES NOT DO
|
|
160
|
+
|
|
161
|
+
- No code runs at install time.
|
|
162
|
+
- It sends no data anywhere except the Factiii servers the owner paired
|
|
163
|
+
with, the owner's own opt-in status page, and the services the owner's
|
|
164
|
+
agents and jobs are told to reach.
|
|
165
|
+
- It does not hide itself. It shows up as `factiii-runner` in process lists
|
|
166
|
+
and as a named login item. `factiii-runner service remove` and
|
|
167
|
+
`npm uninstall -g @factiii/runner` remove it.
|
|
168
|
+
- Nothing in the published code is obfuscated. dist/cli.js is an esbuild
|
|
169
|
+
bundle of the TypeScript source, unminified.
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
CONTACT
|
|
173
|
+
|
|
174
|
+
Publisher: Factiii (https://factiii.com), support@factiii.com
|
package/README.md
CHANGED
|
@@ -5,49 +5,69 @@ A headless daemon that runs Factiii's Board AI agents (Claude-driven coding sess
|
|
|
5
5
|
## Requirements
|
|
6
6
|
|
|
7
7
|
- Node 20+
|
|
8
|
-
- git
|
|
8
|
+
- git and tmux on PATH (installed for you when a space first opens); redis, OrbStack and Tailscale are optional extras
|
|
9
9
|
- The agent CLIs: `claude` and `codex`
|
|
10
|
-
- Optional, by feature: `sops` and `age` (Secrets), Xcode with a simulator (simulator panel, macOS)
|
|
10
|
+
- Optional, by feature: `sops` and `age` (Secrets), Xcode with a simulator (simulator panel, macOS)
|
|
11
11
|
- A Factiii account
|
|
12
12
|
- Outbound network access to the Factiii API server
|
|
13
13
|
|
|
14
14
|
## Install
|
|
15
15
|
|
|
16
16
|
```bash
|
|
17
|
-
|
|
17
|
+
curl -fsSL https://factiii.com/runner.sh | sh
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
It installs the newest release from [github.com/factiii/runner](https://github.com/factiii/runner/releases) after checking its `.sha256`, brings its own Node when the machine has none (or one outside 20 to 24), then runs `factiii-runner setup`. Run it again to update. npm has blocked every release after 0.27.0, so `npm install -g @factiii/runner` installs that old version until npm unblocks the package.
|
|
21
|
+
|
|
22
|
+
Without the script:
|
|
21
23
|
|
|
22
24
|
```bash
|
|
23
|
-
|
|
25
|
+
npm install -g https://github.com/factiii/runner/releases/download/v0.39.0/factiii-runner-0.39.0.tgz
|
|
26
|
+
factiii-runner setup
|
|
24
27
|
```
|
|
25
28
|
|
|
26
29
|
## Usage
|
|
27
30
|
|
|
28
31
|
```bash
|
|
29
|
-
factiii-runner setup # pair
|
|
32
|
+
factiii-runner setup # install and pair the connector, then list the parts
|
|
30
33
|
factiii-runner connect # re-pair with a different account
|
|
31
34
|
factiii-runner start # run the daemon (keep this process alive)
|
|
32
35
|
factiii-runner status # show current config + credential storage state
|
|
36
|
+
factiii-runner parts list | add | remove | start | stop <part> # pick what this runner does
|
|
33
37
|
factiii-runner doctor # check what this machine needs, and fix what the runner may fix
|
|
34
38
|
factiii-runner service install | status | remove # start at login, restart after a crash
|
|
35
39
|
factiii-runner password # enter an old connection password once, to remove it (see Security notes)
|
|
36
40
|
```
|
|
37
41
|
|
|
38
|
-
`setup` walks you through the browser pairing flow. After it finishes, `factiii-runner start` runs the daemon.
|
|
42
|
+
`setup` walks you through the browser pairing flow and installs nothing else: the runner starts as a **connector** (pairing plus the encrypted link to your devices). After it finishes, `factiii-runner start` runs the daemon. Everything else is a part you add (below). A board's own toolchain (git, tmux, node, the Claude CLI, and the board's provider CLI when it is Codex) also installs when you first open a space on the board, with progress shown there; `factiii-runner setup --tools` runs the same install from the terminal.
|
|
43
|
+
|
|
44
|
+
### Parts
|
|
45
|
+
|
|
46
|
+
Each part says what it does, whether it is installed, and about how much disk and memory it costs. The same list is in the app under the runner's Status > Features, where one button adds, removes, starts or stops a part and installs run in the background.
|
|
47
|
+
|
|
48
|
+
| Part | Needs |
|
|
49
|
+
|---|---|
|
|
50
|
+
| `terminals` | git, tmux, script |
|
|
51
|
+
| `claude` / `codex` | node and that agent CLI |
|
|
52
|
+
| `secrets` | sops and age |
|
|
53
|
+
| `simulator` (macOS) | Xcode and an iOS simulator |
|
|
54
|
+
| `local-ai` | Ollama (start and stop run `ollama serve`) |
|
|
55
|
+
| `vault` | its database, PGlite (installed into the runner folder; removing the part keeps your files) |
|
|
56
|
+
|
|
57
|
+
- `add` runs the `doctor` fixes for that part's requirements only. What needs `sudo` or a settings pane is printed, never run.
|
|
58
|
+
- `remove` uninstalls only what `add` installed (kept in `parts.json` in the runner folder), never node, git or script, and never a tool another installed part uses.
|
|
59
|
+
- A part already on the machine reads as installed, so updating an existing runner changes nothing.
|
|
39
60
|
|
|
40
61
|
`doctor` is the first thing to run when a board reports "Couldn't initialize the environment". It prints the resolved location of every tool the runner needs and the PATH it searched, which separates a tool that is genuinely absent from one that is installed somewhere the runner cannot see.
|
|
41
62
|
|
|
42
|
-
### The checklist (`
|
|
63
|
+
### The checklist (`doctor`)
|
|
43
64
|
|
|
44
|
-
`
|
|
65
|
+
`doctor` prints a checklist of the machine at any time. Each item says which feature needs it and whether it is required, so nobody installs Xcode for a runner that never shows a simulator. Only the connector's items are required; every tool is optional, named by the part that needs it. An unmet item gets one of two things:
|
|
45
66
|
|
|
46
67
|
- **"Fix it for me? [Y/n]"** when no administrator is needed: a tool Homebrew or npm installs (tmux, sops, age, the agent CLIs), or the runner's own folder. With a yes the runner installs tools and nothing else.
|
|
47
68
|
- **The command to copy** when it needs `sudo` or is your decision to make: packages on Linux (apt, dnf, pacman), sleep and power settings, automatic login, lingering. The runner prints it and never runs it.
|
|
48
|
-
- **The System Settings path**, and an offer to open that pane, when only a person can do it: Screen Recording and Accessibility for "Factiii Screen". The runner cannot tick the box.
|
|
49
69
|
|
|
50
|
-
The tools of this checklist (git,
|
|
70
|
+
The tools of this checklist (git, tmux, script, node, claude, codex, redis, sops, age, OrbStack, Tailscale) also show in the app, item by item, under the runner's Status > Features. Initialize installs the basics (git, tmux, script, node, claude); each extra (codex, redis for live agent status in terminals, sops and age, OrbStack for containers, Tailscale for remote access) has its own Install button, and Connect Codex installs codex itself. Tailscale's Install also starts tailscaled as a system service (your password, once), makes you its operator, and runs `tailscale up`: open the "Sign in to Tailscale" button it shows, or set `TAILSCALE_AUTH_KEY` (an auth key, or an OAuth client secret with `?preauthorized=true` and its tags) in the runner's environment to join with no sign-in. Screen Sharing then works at `vnc://<its tailnet IP>`, even when Factiii is down.
|
|
51
71
|
|
|
52
72
|
`doctor` exits 1 while a required item is unmet and 0 otherwise. Without a terminal, or with `--no-fix`, it only reports: it asks nothing and changes nothing. `--json` prints the same report for a script.
|
|
53
73
|
|
|
@@ -71,7 +91,7 @@ factiii-runner service remove # stop it and delete what install wrote
|
|
|
71
91
|
|
|
72
92
|
- The service runs `factiii-runner start` with the node and the runner that were installed when you ran `service install`, and the PATH of that terminal. If you move to another Node version or reinstall the runner somewhere else, run `service install` again: it rewrites its file and restarts the service.
|
|
73
93
|
- It restarts the runner after a crash, not after a stop: a runner you disconnect from your account in Settings stays down.
|
|
74
|
-
- Updates approved from the app work as before
|
|
94
|
+
- Updates approved from the app work as before, and the runner also updates itself when nothing is running (on by default; `factiii-runner update auto off`). It relaunches itself; the service is not involved. A new version that fails to start is rolled back to the one before (`factiii-runner update status`).
|
|
75
95
|
- Output goes to `~/.factiii-runner/logs/runner.log`. When it passes 10 MB the runner copies it to `runner.log.1` (replacing the last one) and empties it, at start and once an hour, so the two files are all it ever keeps.
|
|
76
96
|
- If a runner is already running when you install the service (started by hand, or under another process manager), the service is written but not started, so there are never two. Stop the old one and run `service install` again.
|
|
77
97
|
- `install` refuses to overwrite a file of the same name that it did not write, and `remove` deletes only what `install` wrote.
|
|
@@ -94,16 +114,16 @@ factiii-runner service remove # stop it and delete what install wrote
|
|
|
94
114
|
|
|
95
115
|
## Security notes
|
|
96
116
|
|
|
97
|
-
The credentials the runner itself stores in `~/.factiii-runner/` — each board's GitHub PAT
|
|
117
|
+
The credentials the runner itself stores in `~/.factiii-runner/` — each board's GitHub PAT (`<board>/.creds/`), and the pairing JWT (`config.json`) — are **encrypted at rest** with AES-256-GCM at permissions `0600`, all under the same machine keychain key. Existing plaintext files migrate automatically on the first read; no re-pairing. A board's `onedrive.json`, left by the since-removed runner OneDrive index, is deleted on the first read: nothing uses it. The Claude/Codex sign-ins are not in this list: see Provider sign-ins below.
|
|
98
118
|
|
|
99
119
|
**There is no plaintext fallback.** A host with no usable keychain (headless Linux without libsecret, a CI container, a locked login keyring) stores nothing at all: `setup` refuses, and a running daemon connects but fails every credential read and write. It tells you which tool is missing and how to install it, both on the console and in Runner Settings → Secrets. Fix the keyring, restart, and it picks up where it left off.
|
|
100
120
|
|
|
101
121
|
### The machine key, and the connection password that is gone
|
|
102
122
|
|
|
103
123
|
1. **Machine key (always).** A 32-byte key in the OS keychain — macOS Keychain, libsecret on Linux, DPAPI on Windows. Bound to the logged-in OS user, so the daemon works unattended. The runner touches exactly one keychain item (`factiii-runner` / `config-encryption-key`) and never deletes anything; if that item exists but can't be read, it reports the problem rather than minting a replacement over the top of it.
|
|
104
|
-
2. **Connection password (removed).** Older versions let you put a password on top of the machine key. It sealed the GitHub and OneDrive
|
|
124
|
+
2. **Connection password (removed).** Older versions let you put a password on top of the machine key. It sealed the GitHub connections (and the OneDrive ones of the since-removed runner OneDrive index) under a data key (`vault-key.json`), so a password-protected runner came up locked after every restart (including auto-update) and could not clone, deploy, or even show which GitHub user was connected until someone typed it. That password can no longer be set or changed. The connections are sealed under the machine key alone, like the pairing config, and the runner reads them the moment it starts. Values that must stay behind a password belong in deploy secrets (below).
|
|
105
125
|
|
|
106
|
-
**Upgrading a runner that has a password set: one unlock, then never again.** Connection files written before this change are still in the old envelope. With no password set they are converted at the first start. With a password set, the runner needs it **one last time**: it starts, connects, and reports those files as locked (console, and Runner Settings → Secrets) rather than as "no repository". Enter the password once — in the app, at the terminal prompt `start` shows, or with `factiii-runner password` on a host with neither — and every board's files are rewritten under the machine key together. A file is rewritten only after it has been decrypted, through a temp file and a rename, so a failed conversion leaves the old file as it was. **An update approved from the app never waits at a terminal for this.** The relaunch after a self-update skips the terminal prompt even when the runner was started in a terminal — nobody is sitting at it — so the runner connects with those connections locked, prints the problem and the ways to unlock, and the app asks its owner for the password in the same banner that offered the update, on any page. A runner that is unlocked with `factiii-runner password` while it is running notices within a few seconds
|
|
126
|
+
**Upgrading a runner that has a password set: one unlock, then never again.** Connection files written before this change are still in the old envelope. With no password set they are converted at the first start. With a password set, the runner needs it **one last time**: it starts, connects, and reports those files as locked (console, and Runner Settings → Secrets) rather than as "no repository". Enter the password once — in the app, at the terminal prompt `start` shows, or with `factiii-runner password` on a host with neither — and every board's files are rewritten under the machine key together. A file is rewritten only after it has been decrypted, through a temp file and a rename, so a failed conversion leaves the old file as it was. **An update approved from the app never waits at a terminal for this.** The relaunch after a self-update skips the terminal prompt even when the runner was started in a terminal — nobody is sitting at it — so the runner connects with those connections locked, prints the problem and the ways to unlock, and the app asks its owner for the password in the same banner that offered the update, on any page. A runner that is unlocked with `factiii-runner password` while it is running notices within a few seconds and tells its connected clients.
|
|
107
127
|
|
|
108
128
|
**When the vault file goes.** As soon as no file is left in the old envelope — at start, or right after that unlock — `vault-key.json` is renamed to `vault-key.retired.json` and the password stops existing: no later restart asks for it. A runner that has a password set but nothing sealed under it loses the password at start without being asked. If a file will not decrypt even with the vault open, it is left in place and named on the console, and the vault stays until that board is reconnected (which replaces the file).
|
|
109
129
|
|
|
@@ -115,4 +135,4 @@ The Claude/Codex OAuth files are written by those CLIs into each board's state d
|
|
|
115
135
|
|
|
116
136
|
What this protects is **offline** access to the files without the login keychain: a synced folder, a backup, a disk read on another machine. It does **not** protect against someone signed in as the runner's OS user, nor a compromised runner host — the daemon can always read what it can use. Only run a runner on a machine you trust, and only pair with accounts you own.
|
|
117
137
|
|
|
118
|
-
The deploy **Secrets** panel is a separate store with a different model: sops/age, under a password supplied per operation and never cached. The two passwords are independent on purpose — deploy secrets never need to be read unattended, connection tokens do, which is why connection tokens no longer sit behind any password. See `.specs/
|
|
138
|
+
The deploy **Secrets** panel is a separate store with a different model: sops/age, under a password supplied per operation and never cached. The two passwords are independent on purpose — deploy secrets never need to be read unattended, connection tokens do, which is why connection tokens no longer sit behind any password. See `.specs/runner-secrets-store.md`.
|