File Access

Control which paths inside a sandbox can be read or written using ACL rules on each file system mount. Rules are defined per-mount in SandboxConfig.fs[].acls and evaluated at the kernel level before any sandbox process can touch a file.

ACL rules overview

Each ACL rule has two fields:

Field	Description
`path`	A glob pattern matched against the absolute path (e.g. `/workspace/*`, `/workspace/.env`)
`access`	One of `"rw"` (read-write), `"ro"` (read-only), or `"deny"` (block all access)

Rules are matched longest-prefix-first: the rule whose path pattern is the most specific match for a given file path wins. If no rule matches, access is denied by default. A "deny" rule blocks all access regardless of order.

Example: read-write workspace

The simplest policy grants full read-write access to a single mount:

index.ts

import { getOrCreateSandbox } from "hive";

const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [{
    backend: "local",
    mount: "/workspace",
    acls: [
      { path: "/workspace/**", access: "rw" },
    ],
  }],
});

import { getOrCreateSandbox } from "hive";

const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [{
    backend: "local",
    mount: "/workspace",
    acls: [
      { path: "/workspace/**", access: "rw" },
    ],
  }],
});

Everything under /workspace can be read and written. Paths outside the mount are inaccessible.

Example: deny sensitive paths

Combine multiple rules to allow broad read access while blocking secrets and enabling writes only to an output directory:

index.ts

const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [
    {
      backend: "local",
      mount: "/workspace",
      acls: [
        { path: "/workspace/secrets/**", access: "deny" },
        { path: "/workspace/.env",       access: "deny" },
        { path: "/workspace/output/**",  access: "rw"   },
        { path: "/workspace/**",         access: "ro"   },  // fallback: read-only
      ],
    },
  ],
});

const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [
    {
      backend: "local",
      mount: "/workspace",
      acls: [
        { path: "/workspace/secrets/**", access: "deny" },
        { path: "/workspace/.env",       access: "deny" },
        { path: "/workspace/output/**",  access: "rw"   },
        { path: "/workspace/**",         access: "ro"   },  // fallback: read-only
      ],
    },
  ],
});

Because matching is longest-prefix-first, the specific deny rules for secrets/** and .env win over the broad "ro" fallback. The output/** subtree is writable. Everything else under /workspace is readable but not writable.

Changing ACLs at runtime

Use applyConfig to update ACL rules on a running sandbox without restarting it:

index.ts

const current = await sandbox.getConfig();
const result = await sandbox.applyConfig({
  ...current,
  fs: current.fs.map(f =>
    f.mount === "/workspace"
      ? { ...f, acls: [{ path: "/workspace/**", access: "ro" }] }
      : f
  ),
});
console.log(result.applied); // true if applied

const current = await sandbox.getConfig();
const result = await sandbox.applyConfig({
  ...current,
  fs: current.fs.map(f =>
    f.mount === "/workspace"
      ? { ...f, acls: [{ path: "/workspace/**", access: "ro" }] }
      : f
  ),
});
console.log(result.applied); // true if applied

applyConfig returns { applied: true } when the new rules take effect immediately. The change is atomic — there is no window where the old and new rules are both active. Violations of the active ACL rules return EACCES and are recorded in the Audit Log.

Next: Secrets