Fuse Drives

Mount storage into a sandbox via SandboxConfig.fs. Each entry in the fs array defines a backend, a mount path inside the sandbox, and an ACL list that controls read/write access. You can combine multiple backends in a single sandbox — mount paths must be unique and non-overlapping.

Local backend

The local backend stores data on the sandbox's own disk. It has no external dependencies and is the default choice for ephemeral workspaces.

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" }],
  }],
});

Data written to /workspace persists for the lifetime of the sandbox and is discarded when the sandbox is destroyed.

Local with origin (Docker runtime only)

When running the Docker runtime locally for development, you can mount a directory from your host machine into the sandbox by setting origin. This lets the sandbox read and write files directly from your project directory without any copying.

index.ts

const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [{
    backend: "local",
    mount: "/workspace",
    origin: "/Users/me/projects/my-project",  // host path mounted into sandbox
    acls: [{ path: "/workspace/**", access: "rw" }],
  }],
});

const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [{
    backend: "local",
    mount: "/workspace",
    origin: "/Users/me/projects/my-project",  // host path mounted into sandbox
    acls: [{ path: "/workspace/**", access: "rw" }],
  }],
});

origin is only supported with the Docker runtime. It is ignored in cloud environments. Use it to iterate quickly during local development — changes made inside the sandbox are immediately visible on your host, and vice versa.

Google Drive backend

The gdrive backend mounts a Google Drive folder into the sandbox. Authenticate with either OAuth tokens or a service account.

OAuth tokens:

index.ts

const sandbox = await getOrCreateSandbox("drive-sandbox", {
  fs: [{
    backend: "gdrive",
    mount: "/drive",
    gdrive_access_token: process.env.GDRIVE_ACCESS_TOKEN,
    gdrive_refresh_token: process.env.GDRIVE_REFRESH_TOKEN,
    gdrive_client_id: process.env.GDRIVE_CLIENT_ID,
    gdrive_client_secret: process.env.GDRIVE_CLIENT_SECRET,
    gdrive_folder_id: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs",  // optional, scopes to a folder
    acls: [{ path: "/drive/**", access: "rw" }],
  }],
});

const sandbox = await getOrCreateSandbox("drive-sandbox", {
  fs: [{
    backend: "gdrive",
    mount: "/drive",
    gdrive_access_token: process.env.GDRIVE_ACCESS_TOKEN,
    gdrive_refresh_token: process.env.GDRIVE_REFRESH_TOKEN,
    gdrive_client_id: process.env.GDRIVE_CLIENT_ID,
    gdrive_client_secret: process.env.GDRIVE_CLIENT_SECRET,
    gdrive_folder_id: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs",  // optional, scopes to a folder
    acls: [{ path: "/drive/**", access: "rw" }],
  }],
});

Service account:

index.ts

const sandbox = await getOrCreateSandbox("drive-sandbox", {
  fs: [{
    backend: "gdrive",
    mount: "/drive",
    gdrive_service_account_json: process.env.GDRIVE_SERVICE_ACCOUNT_JSON,
    gdrive_folder_id: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs",  // optional
    acls: [{ path: "/drive/**", access: "rw" }],
  }],
});

const sandbox = await getOrCreateSandbox("drive-sandbox", {
  fs: [{
    backend: "gdrive",
    mount: "/drive",
    gdrive_service_account_json: process.env.GDRIVE_SERVICE_ACCOUNT_JSON,
    gdrive_folder_id: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs",  // optional
    acls: [{ path: "/drive/**", access: "rw" }],
  }],
});

When gdrive_folder_id is omitted the entire Drive is mounted. Specifying a folder ID scopes the mount to that folder and its contents.

Field	Description
`gdrive_access_token`	OAuth access token. Required when not using a service account.
`gdrive_refresh_token`	OAuth refresh token used to renew the access token.
`gdrive_client_id`	OAuth client ID from your Google Cloud project.
`gdrive_client_secret`	OAuth client secret from your Google Cloud project.
`gdrive_service_account_json`	Full service account JSON key. Provide this instead of the OAuth fields.
`gdrive_folder_id`	Optional. Google Drive folder ID to scope the mount.

Google Cloud Storage backend

The gcs backend mounts a GCS bucket (or a prefix within one) into the sandbox using a service account for authentication.

index.ts

const sandbox = await getOrCreateSandbox("gcs-sandbox", {
  fs: [{
    backend: "gcs",
    mount: "/storage",
    gcs_bucket: "my-bucket",
    gcs_prefix: "workspace/session-1",  // optional prefix within the bucket
    gcs_service_account_json: process.env.GCS_SERVICE_ACCOUNT_JSON!,
    acls: [{ path: "/storage/**", access: "rw" }],
  }],
});

const sandbox = await getOrCreateSandbox("gcs-sandbox", {
  fs: [{
    backend: "gcs",
    mount: "/storage",
    gcs_bucket: "my-bucket",
    gcs_prefix: "workspace/session-1",  // optional prefix within the bucket
    gcs_service_account_json: process.env.GCS_SERVICE_ACCOUNT_JSON!,
    acls: [{ path: "/storage/**", access: "rw" }],
  }],
});

Field	Description
`gcs_bucket`	GCS bucket name. Required.
`gcs_prefix`	Optional path prefix within the bucket. Only objects under this prefix are visible inside the sandbox.
`gcs_service_account_json`	Full service account JSON key with Storage Object access. Required.

Object keys in the bucket are mapped to file paths under mount. For example, with gcs_prefix: "workspace/session-1", the object workspace/session-1/notes.txt appears as /storage/notes.txt inside the sandbox.

Multiple mounts

You can combine backends by providing multiple entries in the fs array. Mount paths must not overlap.

index.ts

const sandbox = await getOrCreateSandbox("multi-fs", {
  fs: [
    {
      backend: "local",
      mount: "/workspace",
      acls: [{ path: "/workspace/**", access: "rw" }],
    },
    {
      backend: "gcs",
      mount: "/data",
      gcs_bucket: "my-data",
      gcs_service_account_json: process.env.GCS_SERVICE_ACCOUNT_JSON!,
      acls: [{ path: "/data/**", access: "ro" }],
    },
  ],
});

const sandbox = await getOrCreateSandbox("multi-fs", {
  fs: [
    {
      backend: "local",
      mount: "/workspace",
      acls: [{ path: "/workspace/**", access: "rw" }],
    },
    {
      backend: "gcs",
      mount: "/data",
      gcs_bucket: "my-data",
      gcs_service_account_json: process.env.GCS_SERVICE_ACCOUNT_JSON!,
      acls: [{ path: "/data/**", access: "ro" }],
    },
  ],
});

The sandbox can read and write to /workspace while /data is read-only from GCS. Each mount is independent — writing to /workspace does not touch the bucket, and vice versa.

Next: Network Access