Skip to main content
Storage mounts give a runtime filesystem access to object storage or a Git repository at a path such as /mnt/data. Files stream through the host — the guest sees a normal directory, and bucket credentials never enter the guest environment. A bucket can be managed (Gravix Layer provisions it) or external (you connect a bucket you already own). Both mount the same way: kind: "bucket" plus the bucket id or name. Mount paths must be absolute and normalized — not /, no trailing /, no //, no .. segments.
The examples below use two small polling helpers — create-time mounts are usually already attached when the runtime reports running, but waiting explicitly makes the scripts deterministic.

Mount a managed bucket

Provision a bucket, mount it read-write, and use it like a local directory.

Mount an AWS S3 bucket

Connect a bucket you already own once — credentials live in an Identity provider and are resolved host-side — then mount it into any runtime.
For keyless access use auth_mode="oidc" with role_arn and external_id — the platform assumes your role with short-lived credentials instead of storing keys.

Mount an S3-compatible bucket

Any S3-compatible object store works — Cloudflare R2, MinIO, Wasabi, Backblaze B2, or an on-prem endpoint. Set provider to s3_compatible and pass the endpoint; most providers need path_style, and R2 uses region: "auto".
Use prefix to root a connection at a sub-path of the bucket instead of the bucket root.

Mount a public Git repository

A Git mount materializes a read-only checkout on the host — the sandbox never needs network access to the remote. Use depth for a shallow clone and git_ref/ref for a branch, tag, or commit.

Mount a private Git repository

Store the HTTPS token in an Identity provider and reference it — the token stays host-side.

Attach and detach on a running runtime

States and cleanup

GET /v1/agents/runtime/{id}/mounts returns each attachment’s state (attaching, attached, detaching, detached, failed), mode, mount_path, error, and provenance (for Git, the pinned commit).
  • required: true (default) fails the create or attach when a mount cannot attach; required: false records a failed attachment and still starts the runtime.
  • Mounts survive pause/resume, and forked runtimes inherit the parent’s mounts.
  • Killing a runtime detaches every mount automatically.
  • Deleting a mounted bucket returns 409 — detach first.
  • Deleting a managed bucket deletes the provisioned bucket; deleting an external bucket only disconnects it — your data is never touched.
  • Bucket names are unique across managed and external buckets in a project, so bucket: "datasets" always resolves unambiguously.

Endpoints