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 enforced underneath the sandbox before any process can touch a file.

The ACL model

Each rule has two fields:

Rules are matched longest-prefix-first, the most specific matching path wins. If no rule matches, access is denied by default.

Read-write workspace

The simplest policy grants full access to a single mount. This is also the default when you omit fs entirely.

import { getOrCreateSandbox } from "@hiver.sh/client";

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

import { getOrCreateSandbox } from "@hiver.sh/client";

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

Deny sensitive paths

Combine rules to allow broad reads while blocking secrets and permitting writes only to an output directory. Because matching is longest-prefix-first, the specific rules win over the broad fallback regardless of order:

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
  ],
}]

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
  ],
}]

The secrets/** and .env rules block access, output/** is writable, and everything else under /workspace is readable but not writable.

Change ACLs at runtime

Use applyConfig to tighten or loosen access on a running sandbox without restarting it. The change is atomic, there's no window where both old and new rules are active.

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

Access violations return EACCES to the process and are recorded on the event stream as fs.request events with access: "denied", see the Events.

Next: Fuse Drives