Google Cloud Storage

Mount a GCS bucket, or a prefix within one, into a sandbox with the gcs backend, so files persist beyond the sandbox's lifetime. Configure it as an entry in SandboxConfig.fs; access under the mount is governed by ACLs.

Mount a bucket

index.ts

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

const sandbox = await getOrCreateSandbox("gcs", {
  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" }],
  }],
});

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

const sandbox = await getOrCreateSandbox("gcs", {
  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" }],
  }],
});

Fields

Field	Description
`gcs_bucket`	Bucket name. Required.
`gcs_prefix`	Optional key prefix. Only objects under it are visible, mapped to paths under `mount`.
`gcs_service_account_json`	Service account JSON with Storage Object access. Omit to use Application Default Credentials.

How keys map to paths

Object keys under the prefix appear as files under mount. With gcs_prefix: "workspace/session-1", the object workspace/session-1/notes.txt shows up as /storage/notes.txt inside the sandbox. Writes go back to the bucket under the same mapping.

When gcs_service_account_json is omitted, the backend uses Application Default Credentials, GOOGLE_APPLICATION_CREDENTIALS, gcloud user credentials, or the GCE/GKE metadata server, which is convenient when running Hiver inside Google Cloud.

Read-only datasets

Mount a shared dataset read-only by scoping its ACL to ro, and combine it with a writable scratch mount:

index.ts

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" }], // read-only dataset
  },
]

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" }], // read-only dataset
  },
]

Mount paths must be unique and non-overlapping. See Local Files, S3, Azure Blob, and Google Drive for the other backends.

Next: S3