/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.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. Setprovider to s3_compatible and pass the endpoint; most providers need path_style, and R2 uses region: "auto".
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. Usedepth 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: falserecords afailedattachment 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.