@capybara-hq/device 0.1.0-rc.8 → 0.1.0-rc.9

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.
Files changed (46) hide show
  1. package/README.md +90 -179
  2. package/dist/api.d.ts +5 -0
  3. package/dist/args.d.ts +7 -2
  4. package/dist/args.js +33 -16
  5. package/dist/cli.d.ts +7 -5
  6. package/dist/cli.js +20 -31
  7. package/dist/client.d.ts +0 -2
  8. package/dist/client.js +9 -10
  9. package/dist/command-log.d.ts +3 -5
  10. package/dist/commands/login.js +55 -1
  11. package/dist/commands/mode.d.ts +52 -0
  12. package/dist/commands/mode.js +108 -0
  13. package/dist/commands/policy.d.ts +11 -65
  14. package/dist/commands/policy.js +62 -249
  15. package/dist/commands/start.d.ts +2 -2
  16. package/dist/commands/start.js +14 -6
  17. package/dist/commands/status.js +11 -3
  18. package/dist/exec/docker.d.ts +22 -30
  19. package/dist/exec/docker.js +81 -69
  20. package/dist/exec/fs-helper.d.ts +13 -8
  21. package/dist/exec/fs-helper.js +30 -12
  22. package/dist/exec/host.d.ts +8 -8
  23. package/dist/exec/host.js +9 -9
  24. package/dist/exec/os.d.ts +36 -69
  25. package/dist/exec/os.js +65 -159
  26. package/dist/exec/sandbox-messages.d.ts +14 -0
  27. package/dist/exec/sandbox-messages.js +21 -0
  28. package/dist/exec/shared.d.ts +21 -36
  29. package/dist/exec/shared.js +30 -164
  30. package/dist/exec/switch.d.ts +38 -55
  31. package/dist/exec/switch.js +58 -108
  32. package/dist/exec/types.d.ts +8 -18
  33. package/dist/index.d.ts +1 -1
  34. package/dist/network.d.ts +7 -7
  35. package/dist/network.js +11 -18
  36. package/dist/policy-store.d.ts +7 -8
  37. package/dist/policy-store.js +11 -15
  38. package/dist/policy.d.ts +25 -100
  39. package/dist/policy.js +44 -146
  40. package/dist/server-ops.d.ts +15 -35
  41. package/dist/server-ops.js +36 -117
  42. package/dist/state.d.ts +15 -16
  43. package/dist/state.js +38 -36
  44. package/package.json +2 -2
  45. package/dist/proxy-guard.d.ts +0 -58
  46. package/dist/proxy-guard.js +0 -137
package/dist/exec/os.d.ts CHANGED
@@ -1,7 +1,5 @@
1
1
  import { type SandboxAskCallback, type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
2
- import { type DeviceExecArgs, type ExecResult, type SandboxRoots, type SandboxTier } from "@capybara-hq/plugin-sdk";
3
- import { type TierFacts } from "../policy.js";
4
- import { type ProxyGuardResult } from "../proxy-guard.js";
2
+ import { type DeviceExecArgs, type ExecResult, type SandboxRoots } from "@capybara-hq/plugin-sdk";
5
3
  import type { Policy } from "../state.js";
6
4
  import { type ReaperDeps } from "./reap.js";
7
5
  import { type Executor } from "./types.js";
@@ -13,6 +11,8 @@ export declare function sandboxAvailability(): {
13
11
  ok: false;
14
12
  reason: string;
15
13
  };
14
+ /** How to fix an unavailable OS sandbox (shared by the command refusal and the mode switch). */
15
+ export { SANDBOX_INSTALL_HINT, sandboxUnavailableMessage, sandboxUnavailableSwitchRefusal, } from "./sandbox-messages.js";
16
16
  export interface OsExecutorOptions {
17
17
  /** The device directory (from login). */
18
18
  dir: string;
@@ -22,19 +22,16 @@ export interface OsExecutorOptions {
22
22
  home?: string;
23
23
  /** More paths commands may not read (this program's state directory). */
24
24
  denyRead?: string[];
25
- /** The localhost proxy guard (default: {@link detectLocalProxy}); injectable for tests. */
26
- detectProxy?: () => Promise<ProxyGuardResult>;
27
- /** Where the macOS short socket directory is made (default `/private/tmp`). */
28
- socketBase?: string;
29
25
  /** The reaper's process operations (default: the real ones); injectable for tests. */
30
26
  reaper?: Partial<ReaperDeps>;
31
27
  }
32
28
  /**
33
- * Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap):
34
- * writes only under the workspace and tmp roots, the secret paths unreadable, network only to
35
- * the intersection of the local policy and the device's egress. File operations in the
36
- * workspace and tmp roots run in a sandboxed helper too. Construct it with
37
- * {@link createOsExecutor}; the constructor alone serves only `ensureRoot` and the skills root.
29
+ * Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap),
30
+ * today's strict profile (spec §4.4): writes only under the workspace and tmp roots, the secret
31
+ * paths unreadable, no local binding or unix sockets, network only to the intersection of the
32
+ * device's allowlist and the kernel's. File operations in the workspace, tmp and skills roots run
33
+ * in a sandboxed helper too. Construct it with {@link createOsExecutor}; the constructor alone
34
+ * serves only `ensureRoot`.
38
35
  */
39
36
  export declare class OsExecutor implements Executor {
40
37
  private readonly opts;
@@ -50,82 +47,47 @@ export declare class OsExecutor implements Executor {
50
47
  private readonly guard;
51
48
  private readonly files;
52
49
  /**
53
- * The limits of the latest command. The ask callback has no command id; a device belongs to one
54
- * org, so these stand for the org's egress when it explains a refusal.
50
+ * The network limits of the latest command. The ask callback has no command id; a device belongs
51
+ * to one organization, so these stand for its allowlist when it explains a refusal.
55
52
  */
56
53
  private lastLimits;
57
- /** macOS: the short socket directory (TMPDIR in `dev` / `open`); undefined elsewhere. */
58
- private socketDir;
59
- /** The device's package caches (`<dir>/cache`). */
60
- private readonly cacheDir;
61
- /** The latest proxy guard result, and the policy object it was taken for. */
62
- private proxy;
63
- private guardedPolicy;
64
- private guardedAt;
65
54
  /** The configuration the sandbox runs with now, as JSON (see {@link applyConfig}). */
66
55
  private installed;
67
- /**
68
- * Commands spawned while nothing narrowed them (policy `open`, their limits `open`) and still
69
- * running. The ask callback allows any public name only while one runs.
70
- */
71
- private readonly openCommands;
72
56
  /**
73
57
  * Background tasks launched on macOS that still run, by the command id of their launch, with
74
58
  * the task's process group id (its sid). A task keeps its launch's network permissions (the
75
- * per-command list and {@link openCommands}) until its group is gone: it uses the launch's proxy
76
- * credentials long after the launch returned. Checked on the prune tick.
59
+ * per-command list) until its group is gone: it uses the launch's proxy credentials long after
60
+ * the launch returned. Checked on the prune tick.
77
61
  */
78
62
  private readonly backgroundNet;
79
- constructor(opts: OsExecutorOptions);
63
+ /** Whether the OS sandbox can run here; false means sandbox-mode operations are refused. */
64
+ readonly available: boolean;
65
+ /** Why the OS sandbox is unavailable (when {@link available} is false). */
66
+ readonly unavailableReason: string | undefined;
67
+ constructor(opts: OsExecutorOptions, state?: {
68
+ unavailable?: string;
69
+ });
70
+ /** Throws the actionable refusal when the OS sandbox is unavailable. */
71
+ private requireSandbox;
72
+ /** The sandbox configuration (no domains: those are per command). */
73
+ config(): SandboxRuntimeConfig;
80
74
  /**
81
- * The tier of work that has no limits of its own (the file helper): the device's choice cut to
82
- * the latest exec's ceiling, `strict` before any exec (no ceiling known yet).
83
- */
84
- tier(policy?: Policy): SandboxTier;
85
- /** What the tier gives on this machine now (for the policy summary). */
86
- tierFacts(policy?: Policy): TierFacts;
87
- /** The latest proxy guard result. */
88
- proxyGuard(): ProxyGuardResult;
89
- /** The sandbox configuration for the policy at `tier` (no domains: those are per command). */
90
- config(policy?: Policy, tier?: SandboxTier): SandboxRuntimeConfig;
91
- /**
92
- * Installs {@link config} when the policy or the tier changed it, so the change applies at the
93
- * next command without a restart. The runtime reads its global configuration at each wrap.
75
+ * Installs {@link config} when it changed, so a policy change applies at the next command
76
+ * without a restart. The runtime reads its global configuration at each wrap.
94
77
  */
95
78
  private applyConfig;
96
79
  /** Records the configuration the sandbox was initialized with. */
97
80
  markInstalled(config: SandboxRuntimeConfig): void;
98
- /**
99
- * macOS: makes the short socket directory (0700) at creation, and again before a `dev` / `open`
100
- * command when it is gone (macOS prunes /tmp). A path taken by something else leaves the
101
- * device without one: commands then use the tmp root.
102
- */
103
- prepareSocketDir(): void;
104
- /**
105
- * Runs the localhost proxy guard at creation, when the policy was reloaded since the last run
106
- * (the store returns a new object for each new version of policy.json), and when the last result
107
- * is older than {@link PROXY_GUARD_TTL_MS} (a proxy started after this program). A guard that
108
- * fails counts as a proxy found (fail safe; `localhost: allow` still overrides).
109
- */
110
- refreshProxyGuard(policy: Policy): Promise<void>;
111
81
  ensureRoot(): Promise<"ok" | "gone">;
112
82
  /**
113
- * The sandbox's ask callback, reached only for a host no list allows. sandbox-runtime refuses `*`
114
- * in a per-command list, so a command that may reach any host (device policy `open`, its limits
115
- * `open`) is allowed here: a public name is allowed while such a command runs and the policy
116
- * and latest limits still say so (narrowing takes effect at once). The callback has no command
117
- * id, so a concurrent command of the same device may ride along meanwhile; the file helper never
118
- * opens it. Otherwise it refuses, with a reason clients that print the proxy's status phrase
119
- * show (spec §9.1).
83
+ * The sandbox's ask callback, reached only for a host no list allows: it refuses, with a reason
84
+ * clients that print the proxy's status phrase show (spec §9.1). Sandbox mode has no
85
+ * "any host" state (auto mode runs without the OS sandbox and has the machine's network), so
86
+ * this never allows.
120
87
  */
121
88
  readonly askCallback: SandboxAskCallback;
122
89
  /** The classified network refusals of one command (read before it unregisters). */
123
90
  private blockedFor;
124
- /**
125
- * `<dir>/git-template`, an empty directory commands can read but not write (it is outside the
126
- * roots), made on demand; undefined when it cannot be made.
127
- */
128
- private gitTemplate;
129
91
  /**
130
92
  * The marker value of a tag's processes. An exec's processes carry `<this>.<exec id>` (see
131
93
  * {@link execMarker}); {@link killTagged} matches both.
@@ -138,7 +100,7 @@ export declare class OsExecutor implements Executor {
138
100
  * exported) and spawns it as the leader of a new process group.
139
101
  */
140
102
  private spawnSandboxed;
141
- /** Drops a command's network permissions (its per-command list and any-host membership). */
103
+ /** Drops a command's network permissions (its per-command list). */
142
104
  private releaseNet;
143
105
  /** Keeps a launched background task's network permissions while its group `sid` lives. */
144
106
  private keepBackgroundNet;
@@ -179,5 +141,10 @@ export declare function launchedGroup(stdout: string, platform?: NodeJS.Platform
179
141
  * The OS sandbox executor: checks the platform and dependencies, starts the sandbox's proxies
180
142
  * once for this process, and kills what a previous run of this device left running.
181
143
  * Network is denied unless a command's own list allows it.
144
+ *
145
+ * When the OS sandbox is unavailable (an unsupported platform or missing dependencies) this still
146
+ * returns an executor, marked unavailable, so `start` keeps serving: auto mode works, and every
147
+ * sandbox-mode command or file operation is refused with the actionable reason
148
+ * ({@link sandboxUnavailableMessage}) instead of running unsandboxed or stopping the device.
182
149
  */
183
150
  export declare function createOsExecutor(opts: OsExecutorOptions): Promise<OsExecutor>;
package/dist/exec/os.js CHANGED
@@ -1,17 +1,17 @@
1
1
  import { spawn } from "node:child_process";
2
2
  import { createHash, randomBytes } from "node:crypto";
3
- import { existsSync, lstatSync, mkdirSync, realpathSync } from "node:fs";
3
+ import { existsSync, realpathSync } from "node:fs";
4
4
  import { homedir, constants as osConstants } from "node:os";
5
- import { join, resolve } from "node:path";
5
+ import { resolve } from "node:path";
6
6
  import { SandboxManager, } from "@anthropic-ai/sandbox-runtime";
7
7
  import { isBackgroundLaunch, } from "@capybara-hq/plugin-sdk";
8
- import { blockedHosts, denyReason, isPublicName, networkTrailer, } from "../network.js";
9
- import { ANY_HOST, deviceTier, effectiveEgress, grantedHosts, srtConfig, tierFacts, } from "../policy.js";
10
- import { detectLocalProxy, PROXY_GUARD_TTL_MS } from "../proxy-guard.js";
8
+ import { blockedHosts, denyReason, networkTrailer } from "../network.js";
9
+ import { effectiveEgress, grantedHosts, srtConfig } from "../policy.js";
11
10
  import { FS_HELPER_SCRIPT } from "./fs-helper.js";
12
11
  import { EXEC_MARKER, killMarked } from "./procs.js";
13
12
  import { Reaper } from "./reap.js";
14
- import { cacheEnv, cacheRoot, ENV_NAME_RE, HostFiles, isUnder, OutputCap, osRoots, PIPE_GRACE_MS, policyError, prepareSocketDir, RootGuard, shellQuote, socketDirPath, toolHomeEnv, } from "./shared.js";
13
+ import { sandboxUnavailableMessage } from "./sandbox-messages.js";
14
+ import { ENV_NAME_RE, HostFiles, isUnder, OutputCap, osRoots, PIPE_GRACE_MS, policyError, RootGuard, shellQuote, toolHomeEnv, } from "./shared.js";
15
15
  import { DeviceOpError } from "./types.js";
16
16
  export { osRoots, ROOT_MARKER, utf8Prefix } from "./shared.js";
17
17
  /** A file operation in the sandboxed helper that takes longer than this is killed. */
@@ -40,6 +40,8 @@ export function sandboxAvailability() {
40
40
  }
41
41
  return { ok: true };
42
42
  }
43
+ /** How to fix an unavailable OS sandbox (shared by the command refusal and the mode switch). */
44
+ export { SANDBOX_INSTALL_HINT, sandboxUnavailableMessage, sandboxUnavailableSwitchRefusal, } from "./sandbox-messages.js";
43
45
  /** Sends SIGKILL to a process group; false when the group no longer exists. */
44
46
  function killGroupId(pgid, signal = "SIGKILL") {
45
47
  try {
@@ -60,11 +62,12 @@ function pidAlive(pid) {
60
62
  }
61
63
  }
62
64
  /**
63
- * Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap):
64
- * writes only under the workspace and tmp roots, the secret paths unreadable, network only to
65
- * the intersection of the local policy and the device's egress. File operations in the
66
- * workspace and tmp roots run in a sandboxed helper too. Construct it with
67
- * {@link createOsExecutor}; the constructor alone serves only `ensureRoot` and the skills root.
65
+ * Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap),
66
+ * today's strict profile (spec §4.4): writes only under the workspace and tmp roots, the secret
67
+ * paths unreadable, no local binding or unix sockets, network only to the intersection of the
68
+ * device's allowlist and the kernel's. File operations in the workspace, tmp and skills roots run
69
+ * in a sandboxed helper too. Construct it with {@link createOsExecutor}; the constructor alone
70
+ * serves only `ensureRoot`.
68
71
  */
69
72
  export class OsExecutor {
70
73
  opts;
@@ -80,79 +83,55 @@ export class OsExecutor {
80
83
  guard;
81
84
  files;
82
85
  /**
83
- * The limits of the latest command. The ask callback has no command id; a device belongs to one
84
- * org, so these stand for the org's egress when it explains a refusal.
86
+ * The network limits of the latest command. The ask callback has no command id; a device belongs
87
+ * to one organization, so these stand for its allowlist when it explains a refusal.
85
88
  */
86
89
  lastLimits;
87
- /** macOS: the short socket directory (TMPDIR in `dev` / `open`); undefined elsewhere. */
88
- socketDir;
89
- /** The device's package caches (`<dir>/cache`). */
90
- cacheDir;
91
- /** The latest proxy guard result, and the policy object it was taken for. */
92
- proxy = { detected: false, reasons: [] };
93
- guardedPolicy;
94
- guardedAt = 0;
95
90
  /** The configuration the sandbox runs with now, as JSON (see {@link applyConfig}). */
96
91
  installed;
97
- /**
98
- * Commands spawned while nothing narrowed them (policy `open`, their limits `open`) and still
99
- * running. The ask callback allows any public name only while one runs.
100
- */
101
- openCommands = new Set();
102
92
  /**
103
93
  * Background tasks launched on macOS that still run, by the command id of their launch, with
104
94
  * the task's process group id (its sid). A task keeps its launch's network permissions (the
105
- * per-command list and {@link openCommands}) until its group is gone: it uses the launch's proxy
106
- * credentials long after the launch returned. Checked on the prune tick.
95
+ * per-command list) until its group is gone: it uses the launch's proxy credentials long after
96
+ * the launch returned. Checked on the prune tick.
107
97
  */
108
98
  backgroundNet = new Map();
109
- constructor(opts) {
99
+ /** Whether the OS sandbox can run here; false means sandbox-mode operations are refused. */
100
+ available;
101
+ /** Why the OS sandbox is unavailable (when {@link available} is false). */
102
+ unavailableReason;
103
+ constructor(opts, state = {}) {
110
104
  this.opts = opts;
105
+ this.available = state.unavailable === undefined;
106
+ this.unavailableReason = state.unavailable;
111
107
  this.reaper = new Reaper(opts.reaper);
112
108
  const dir = resolve(opts.dir);
113
109
  // The roots are reported as real paths, so what commands print matches what the kernel sends.
114
110
  this.dir = existsSync(dir) ? realpathSync(dir) : dir;
115
111
  this.roots = osRoots(this.dir);
116
112
  this.guard = new RootGuard(this.dir, this.roots);
117
- this.files = new HostFiles(this.roots);
113
+ this.files = new HostFiles(this.roots, "sandbox");
118
114
  this.dirKey = createHash("sha256").update(this.dir).digest("hex").slice(0, 16);
119
- this.cacheDir = cacheRoot(this.dir);
120
- }
121
- /**
122
- * The tier of work that has no limits of its own (the file helper): the device's choice cut to
123
- * the latest exec's ceiling, `strict` before any exec (no ceiling known yet).
124
- */
125
- tier(policy = this.opts.policy()) {
126
- return this.lastLimits === undefined ? "strict" : deviceTier(policy, this.lastLimits);
127
- }
128
- /** What the tier gives on this machine now (for the policy summary). */
129
- tierFacts(policy = this.opts.policy()) {
130
- return tierFacts(policy, this.lastLimits, {
131
- proxyDetected: this.proxy.detected,
132
- mode: "os",
133
- });
134
115
  }
135
- /** The latest proxy guard result. */
136
- proxyGuard() {
137
- return this.proxy;
116
+ /** Throws the actionable refusal when the OS sandbox is unavailable. */
117
+ requireSandbox() {
118
+ if (!this.available) {
119
+ throw new DeviceOpError("error", sandboxUnavailableMessage(this.unavailableReason ?? ""));
120
+ }
138
121
  }
139
- /** The sandbox configuration for the policy at `tier` (no domains: those are per command). */
140
- config(policy = this.opts.policy(), tier = this.tier(policy)) {
141
- return srtConfig(policy, this.roots, [], {
142
- tier,
122
+ /** The sandbox configuration (no domains: those are per command). */
123
+ config() {
124
+ return srtConfig(this.roots, [], {
143
125
  ...(this.opts.home !== undefined && { home: this.opts.home }),
144
126
  ...(this.opts.denyRead !== undefined && { denyRead: this.opts.denyRead }),
145
- proxyDetected: this.proxy.detected,
146
- ...(this.socketDir !== undefined && { socketDir: this.socketDir }),
147
- cacheDir: this.cacheDir,
148
127
  });
149
128
  }
150
129
  /**
151
- * Installs {@link config} when the policy or the tier changed it, so the change applies at the
152
- * next command without a restart. The runtime reads its global configuration at each wrap.
130
+ * Installs {@link config} when it changed, so a policy change applies at the next command
131
+ * without a restart. The runtime reads its global configuration at each wrap.
153
132
  */
154
- applyConfig(policy, tier) {
155
- const config = this.config(policy, tier);
133
+ applyConfig() {
134
+ const config = this.config();
156
135
  const json = JSON.stringify(config);
157
136
  if (json === this.installed)
158
137
  return;
@@ -164,60 +143,17 @@ export class OsExecutor {
164
143
  markInstalled(config) {
165
144
  this.installed = JSON.stringify(config);
166
145
  }
167
- /**
168
- * macOS: makes the short socket directory (0700) at creation, and again before a `dev` / `open`
169
- * command when it is gone (macOS prunes /tmp). A path taken by something else leaves the
170
- * device without one: commands then use the tmp root.
171
- */
172
- prepareSocketDir() {
173
- if (process.platform !== "darwin")
174
- return;
175
- this.socketDir = prepareSocketDir(socketDirPath(this.dirKey, this.opts.socketBase));
176
- }
177
- /**
178
- * Runs the localhost proxy guard at creation, when the policy was reloaded since the last run
179
- * (the store returns a new object for each new version of policy.json), and when the last result
180
- * is older than {@link PROXY_GUARD_TTL_MS} (a proxy started after this program). A guard that
181
- * fails counts as a proxy found (fail safe; `localhost: allow` still overrides).
182
- */
183
- async refreshProxyGuard(policy) {
184
- const now = Date.now();
185
- if (policy === this.guardedPolicy && now - this.guardedAt < PROXY_GUARD_TTL_MS)
186
- return;
187
- this.guardedPolicy = policy;
188
- this.guardedAt = now;
189
- try {
190
- this.proxy = await (this.opts.detectProxy ?? (() => detectLocalProxy()))();
191
- }
192
- catch (e) {
193
- this.proxy = {
194
- detected: true,
195
- reasons: [`the localhost proxy guard failed: ${e.message}`],
196
- };
197
- }
198
- }
199
146
  async ensureRoot() {
200
147
  return this.guard.ensure();
201
148
  }
202
149
  /**
203
- * The sandbox's ask callback, reached only for a host no list allows. sandbox-runtime refuses `*`
204
- * in a per-command list, so a command that may reach any host (device policy `open`, its limits
205
- * `open`) is allowed here: a public name is allowed while such a command runs and the policy
206
- * and latest limits still say so (narrowing takes effect at once). The callback has no command
207
- * id, so a concurrent command of the same device may ride along meanwhile; the file helper never
208
- * opens it. Otherwise it refuses, with a reason clients that print the proxy's status phrase
209
- * show (spec §9.1).
150
+ * The sandbox's ask callback, reached only for a host no list allows: it refuses, with a reason
151
+ * clients that print the proxy's status phrase show (spec §9.1). Sandbox mode has no
152
+ * "any host" state (auto mode runs without the OS sandbox and has the machine's network), so
153
+ * this never allows.
210
154
  */
211
155
  askCallback = async ({ host }) => {
212
- const policy = this.opts.policy();
213
- const limits = this.lastLimits;
214
- if (this.openCommands.size > 0 &&
215
- limits !== undefined &&
216
- effectiveEgress(policy, limits).includes(ANY_HOST) &&
217
- isPublicName(host)) {
218
- return true;
219
- }
220
- return { allow: false, reason: denyReason(host, limits, policy) };
156
+ return { allow: false, reason: denyReason(host, this.lastLimits, this.opts.policy()) };
221
157
  };
222
158
  /** The classified network refusals of one command (read before it unregisters). */
223
159
  blockedFor(commandId, limits, policy) {
@@ -226,20 +162,6 @@ export class OsExecutor {
226
162
  .map((v) => v.line);
227
163
  return blockedHosts(lines, limits, policy);
228
164
  }
229
- /**
230
- * `<dir>/git-template`, an empty directory commands can read but not write (it is outside the
231
- * roots), made on demand; undefined when it cannot be made.
232
- */
233
- gitTemplate() {
234
- const path = join(this.dir, "git-template");
235
- try {
236
- mkdirSync(path, { recursive: true, mode: 0o755 });
237
- return lstatSync(path).isDirectory() ? path : undefined;
238
- }
239
- catch {
240
- return undefined;
241
- }
242
- }
243
165
  /**
244
166
  * The marker value of a tag's processes. An exec's processes carry `<this>.<exec id>` (see
245
167
  * {@link execMarker}); {@link killTagged} matches both.
@@ -257,14 +179,6 @@ export class OsExecutor {
257
179
  */
258
180
  async spawnSandboxed(script, o) {
259
181
  const exports = [];
260
- const dev = o.tier !== "strict";
261
- // Re-checked before every dev / open command (macOS prunes /tmp, and a path swapped for a
262
- // link or another user's directory must not be used): prepareSocketDir never follows links.
263
- if (dev && process.platform === "darwin")
264
- this.prepareSocketDir();
265
- // dev / open on macOS: the short socket directory, where unix sockets are allowed.
266
- const tmp = dev && this.socketDir !== undefined ? this.socketDir : this.roots.tmp;
267
- const gitTemplate = dev ? this.gitTemplate() : undefined;
268
182
  const inner = {
269
183
  // The user's PATH applies inside the sandbox only (the wrapper runs with OUTER_ENV).
270
184
  PATH: process.env.PATH ?? "/usr/bin:/bin:/usr/sbin:/sbin",
@@ -273,18 +187,12 @@ export class OsExecutor {
273
187
  TERM: "dumb",
274
188
  HOME: this.roots.workspace,
275
189
  ...(process.env.USER !== undefined && { USER: process.env.USER }),
276
- // Version managers (asdf, nvm, pyenv, ...) read their data under the real home, at every
277
- // tier: HOME is the workspace here. Read only; the request's values win.
190
+ // Version managers (asdf, nvm, pyenv, ...) read their data under the real home: HOME is the
191
+ // workspace here. Read only; the request's values win.
278
192
  ...toolHomeEnv(this.opts.home ?? homedir()),
279
- // dev / open: package caches under <dir>/cache; the command's own values win.
280
- ...(dev && cacheEnv(this.cacheDir, { create: true })),
281
- // dev / open may write .git/config but never .git/hooks: init and clone copy no sample hooks.
282
- ...(dev && gitTemplate !== undefined && { GIT_TEMPLATE_DIR: gitTemplate }),
283
193
  ...o.env,
284
194
  // The runtime points TMPDIR at its own /tmp/claude (denied by the config): use ours.
285
- TMPDIR: tmp,
286
- // Chromium on macOS ignores TMPDIR and reads this instead (its singleton socket).
287
- ...(process.platform === "darwin" && { MAC_CHROMIUM_TMPDIR: tmp }),
195
+ TMPDIR: this.roots.tmp,
288
196
  [EXEC_MARKER]: o.marker,
289
197
  };
290
198
  for (const [k, v] of Object.entries(inner)) {
@@ -292,15 +200,13 @@ export class OsExecutor {
292
200
  throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
293
201
  exports.push(`export ${k}=${shellQuote(v)}`);
294
202
  }
295
- this.applyConfig(o.policy, o.tier);
203
+ this.applyConfig();
296
204
  const commandId = randomBytes(16).toString("base64url");
297
205
  const wrapped = await SandboxManager.wrapWithSandbox(`${exports.join("\n")}\n${script}`, "/bin/bash", undefined, o.signal, { commandId, commandText: script });
298
206
  // The kernel may have cancelled while the wrap was prepared.
299
207
  o.signal?.throwIfAborted();
300
- // "*" (any host) is refused in a per-command list: the ask callback allows those hosts.
301
- const listed = o.egress.filter((d) => d !== ANY_HOST);
302
- if (listed.length > 0) {
303
- SandboxManager.registerCommandNetworkLists(commandId, { allowedDomains: listed });
208
+ if (o.egress.length > 0) {
209
+ SandboxManager.registerCommandNetworkLists(commandId, { allowedDomains: o.egress });
304
210
  }
305
211
  let child;
306
212
  try {
@@ -319,10 +225,9 @@ export class OsExecutor {
319
225
  }
320
226
  return { child, commandId };
321
227
  }
322
- /** Drops a command's network permissions (its per-command list and any-host membership). */
228
+ /** Drops a command's network permissions (its per-command list). */
323
229
  releaseNet(commandId) {
324
230
  this.backgroundNet.delete(commandId);
325
- this.openCommands.delete(commandId);
326
231
  SandboxManager.unregisterCommandNetworkLists(commandId);
327
232
  }
328
233
  /** Keeps a launched background task's network permissions while its group `sid` lives. */
@@ -384,15 +289,15 @@ export class OsExecutor {
384
289
  }
385
290
  async exec(args, signal) {
386
291
  signal.throwIfAborted();
292
+ this.requireSandbox();
387
293
  const cwd = await this.files.inside(args.cwd ?? this.roots.workspace, "cwd");
388
294
  // Read once: the command's lists and the explanation of its refusals use the same policy.
389
295
  const policy = this.opts.policy();
390
296
  this.lastLimits = args.limits;
391
- await this.refreshProxyGuard(policy);
392
297
  // A granted host the command still could not reach is not the device's doing.
393
298
  const judged = {
394
299
  ...policy,
395
- allowedDomains: [...policy.allowedDomains, ...grantedHosts(policy, args.limits, args.grants)],
300
+ allowedDomains: [...policy.allowedDomains, ...grantedHosts(args.limits, args.grants)],
396
301
  };
397
302
  const egress = effectiveEgress(policy, args.limits, args.grants);
398
303
  const marker = this.execMarker(args.tag);
@@ -403,12 +308,8 @@ export class OsExecutor {
403
308
  ...(args.env !== undefined && { env: args.env }),
404
309
  marker,
405
310
  egress,
406
- policy,
407
- tier: deviceTier(policy, args.limits),
408
311
  signal,
409
312
  });
410
- if (egress.includes(ANY_HOST))
411
- this.openCommands.add(commandId);
412
313
  return new Promise((resolvePromise, reject) => {
413
314
  const cap = new OutputCap(args.maxOutputBytes);
414
315
  let timedOut = false;
@@ -519,6 +420,7 @@ export class OsExecutor {
519
420
  process.execPath,
520
421
  "-e",
521
422
  FS_HELPER_SCRIPT,
423
+ "sandbox",
522
424
  op,
523
425
  path,
524
426
  String(maxBytes),
@@ -531,8 +433,6 @@ export class OsExecutor {
531
433
  cwd: this.roots.workspace,
532
434
  marker: this.markerOf("fs-helper"),
533
435
  egress: [],
534
- policy: this.opts.policy(),
535
- tier: this.tier(),
536
436
  stdin: data !== undefined,
537
437
  });
538
438
  const chunks = [];
@@ -578,6 +478,7 @@ export class OsExecutor {
578
478
  return res.r ?? null;
579
479
  }
580
480
  async readFile(path, maxBytes) {
481
+ this.requireSandbox();
581
482
  const p = this.files.lexical(path);
582
483
  if (isUnder(p, this.roots.skills))
583
484
  return this.files.read(path, maxBytes);
@@ -585,12 +486,14 @@ export class OsExecutor {
585
486
  return r === null ? null : { data: Buffer.from(r.b64, "base64"), truncated: r.truncated };
586
487
  }
587
488
  async writeFile(path, data) {
489
+ this.requireSandbox();
588
490
  const p = this.files.lexical(path);
589
491
  if (isUnder(p, this.roots.skills))
590
492
  return this.files.write(path, data);
591
493
  await this.helper("write", p, 0, data);
592
494
  }
593
495
  async stat(path) {
496
+ this.requireSandbox();
594
497
  const p = this.files.lexical(path);
595
498
  if (isUnder(p, this.roots.skills)) {
596
499
  return this.files.stat(path);
@@ -627,7 +530,8 @@ export class OsExecutor {
627
530
  if (this.pruneTimer !== undefined)
628
531
  clearInterval(this.pruneTimer);
629
532
  this.pruneTimer = undefined;
630
- await SandboxManager.reset();
533
+ if (this.available)
534
+ await SandboxManager.reset();
631
535
  }
632
536
  }
633
537
  /**
@@ -645,18 +549,20 @@ export function launchedGroup(stdout, platform = process.platform) {
645
549
  * The OS sandbox executor: checks the platform and dependencies, starts the sandbox's proxies
646
550
  * once for this process, and kills what a previous run of this device left running.
647
551
  * Network is denied unless a command's own list allows it.
552
+ *
553
+ * When the OS sandbox is unavailable (an unsupported platform or missing dependencies) this still
554
+ * returns an executor, marked unavailable, so `start` keeps serving: auto mode works, and every
555
+ * sandbox-mode command or file operation is refused with the actionable reason
556
+ * ({@link sandboxUnavailableMessage}) instead of running unsandboxed or stopping the device.
648
557
  */
649
558
  export async function createOsExecutor(opts) {
650
559
  const available = sandboxAvailability();
651
560
  if (!available.ok)
652
- throw new Error(available.reason);
561
+ return new OsExecutor(opts, { unavailable: available.reason });
653
562
  const executor = new OsExecutor(opts);
654
- executor.prepareSocketDir();
655
- const policy = opts.policy();
656
- await executor.refreshProxyGuard(policy);
657
563
  // The ask callback never allows: a destination outside the lists is refused, with a reason
658
564
  // when this runtime carries one (an older runtime would read any answer object as an allow).
659
- const config = executor.config(policy);
565
+ const config = executor.config();
660
566
  await SandboxManager.initialize(config, SandboxManager.askCallbackDenyReason === true ? executor.askCallback : undefined);
661
567
  executor.markInstalled(config);
662
568
  await executor.killLeftovers();
@@ -0,0 +1,14 @@
1
+ /**
2
+ * The texts of an unavailable OS sandbox (spec 2026-11-14 direction): sandbox mode must refuse a
3
+ * command with a clear, actionable reason while auto mode keeps working. Pure strings, so the
4
+ * `mode` command can use them without loading the sandbox runtime.
5
+ */
6
+ /** How to fix an unavailable OS sandbox (shared by the command refusal and the mode switch). */
7
+ export declare const SANDBOX_INSTALL_HINT = "install the sandbox dependencies (bubblewrap and socat on Linux) and restart capybara-device";
8
+ /**
9
+ * The refusal of every sandbox-mode operation when the OS sandbox is unavailable (device protocol
10
+ * error kind `error`): actionable, and never a silent fallback to running unsandboxed.
11
+ */
12
+ export declare function sandboxUnavailableMessage(reason: string): string;
13
+ /** The refusal of `capybara-device mode sandbox` when the OS sandbox is unavailable. */
14
+ export declare function sandboxUnavailableSwitchRefusal(reason: string): string;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The texts of an unavailable OS sandbox (spec 2026-11-14 direction): sandbox mode must refuse a
3
+ * command with a clear, actionable reason while auto mode keeps working. Pure strings, so the
4
+ * `mode` command can use them without loading the sandbox runtime.
5
+ */
6
+ /** How to fix an unavailable OS sandbox (shared by the command refusal and the mode switch). */
7
+ export const SANDBOX_INSTALL_HINT = "install the sandbox dependencies (bubblewrap and socat on Linux) and restart capybara-device";
8
+ /**
9
+ * The refusal of every sandbox-mode operation when the OS sandbox is unavailable (device protocol
10
+ * error kind `error`): actionable, and never a silent fallback to running unsandboxed.
11
+ */
12
+ export function sandboxUnavailableMessage(reason) {
13
+ return (`The OS sandbox is unavailable on this machine (${reason}), so commands cannot run in sandbox ` +
14
+ "mode. Run `capybara-device mode auto` on this machine to use auto mode, or " +
15
+ `${SANDBOX_INSTALL_HINT}.`);
16
+ }
17
+ /** The refusal of `capybara-device mode sandbox` when the OS sandbox is unavailable. */
18
+ export function sandboxUnavailableSwitchRefusal(reason) {
19
+ return (`Nothing changed: the OS sandbox is unavailable on this machine (${reason}), so sandbox mode ` +
20
+ `could not run commands. Stay in auto mode, or ${SANDBOX_INSTALL_HINT} and try again.`);
21
+ }