> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Storage Mounts

> Mount S3, S3-compatible, and Git storage inside a runtime

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.

| To mount | Use | Access |
| - | - | - |
| A managed bucket | `kind: "bucket"`, `bucket: <id-or-name>` | `ro` default, `rw` supported |
| Your S3 or S3-compatible bucket | `kind: "bucket"`, `bucket: <id-or-name>` | `ro` default, `rw` supported |
| A Git repository | `kind: "git"`, `url` | Read-only |

Mount paths must be absolute and normalized — not `/`, no trailing `/`, no `//`, no `..` segments.

> [!NOTE]
>
> 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.
>
> ```python Python theme={null}
> import time
>
> def wait_bucket(client, bucket_id):
>     while client.storage.buckets.get(bucket_id).status != "active":
>         time.sleep(2)
>
> def wait_mount(sandbox, path):
>     while True:
>         m = next((m for m in sandbox.mounts.list().mounts if m.mount_path == path), None)
>         if m and m.state == "attached":
>             return m
>         if m and m.state == "failed":
>             raise RuntimeError(m.error)
>         time.sleep(2)
> ```
>
> ```typescript TypeScript theme={null}
> import type { GravixLayer, Runtime } from 'gravixlayer';
>
> const waitBucket = async (client: GravixLayer, id: string) => {
>   while ((await client.storage.buckets.get(id)).status !== 'active') {
>     await new Promise((r) => setTimeout(r, 2000));
>   }
> };
>
> const waitMount = async (sandbox: Runtime, path: string) => {
>   for (;;) {
>     const m = (await sandbox.mounts.list()).mounts.find((x) => x.mountPath === path);
>     if (m?.state === 'attached') return m;
>     if (m?.state === 'failed') throw new Error(m.error);
>     await new Promise((r) => setTimeout(r, 2000));
>   }
> };
> ```

## Mount a managed bucket

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

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
bucket = client.storage.buckets.create("datasets")
wait_bucket(client, bucket.id)

sandbox = client.runtime.create(mounts=[{
    "kind": "bucket", "path": "/mnt/data", "bucket": bucket.id, "mode": "rw",
}])
wait_mount(sandbox, "/mnt/data")

print(sandbox.run_cmd(
    "sh", ["-c", "echo hello > /mnt/data/hi.txt && cat /mnt/data/hi.txt"]
).stdout)
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const bucket = await client.storage.buckets.create('datasets');
await waitBucket(client, bucket.id);

const sandbox = await client.runtime.create({
  mounts: [{ kind: 'bucket', path: '/mnt/data', bucket: bucket.id, mode: 'rw' }],
});
await waitMount(sandbox, '/mnt/data');

console.log(
  (await sandbox.runCmd('echo hello > /mnt/data/hi.txt && cat /mnt/data/hi.txt')).stdout,
);
```

```bash CLI theme={null}
BUCKET_ID=$(gravixlayer storage bucket create datasets --output json | jq -r '.id')
until [ "$(gravixlayer storage bucket get "$BUCKET_ID" --output json | jq -r '.status')" = "active" ]; do sleep 2; done

RT=$(gravixlayer runtime create --wait --output json \
  --mount "{\"kind\":\"bucket\",\"path\":\"/mnt/data\",\"bucket\":\"$BUCKET_ID\",\"mode\":\"rw\"}" \
  | jq -r '.runtime_id')
gravixlayer runtime exec "$RT" -- sh -c 'echo hello > /mnt/data/hi.txt && cat /mnt/data/hi.txt'
```

```bash cURL theme={null}
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/buckets" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"datasets"}'

curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json" \
  -d '{"template":"base-desktop","cloud":"aws","region":"us-east-1","mounts":[{"kind":"bucket","path":"/mnt/data","bucket":"<bucket-id>","mode":"rw"}]}'
```

## 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.

```python Python theme={null}
import os
from gravixlayer import GravixLayer

client = GravixLayer()
provider = client.identity.providers.create(
    "aws-creds",
    secrets=[
        {"key": "AWS_ACCESS_KEY_ID", "value": os.environ["AWS_ACCESS_KEY_ID"]},
        {"key": "AWS_SECRET_ACCESS_KEY", "value": os.environ["AWS_SECRET_ACCESS_KEY"]},
    ],
)
bucket = client.storage.buckets.connect(
    "my-s3",
    os.environ["EXTERNAL_BUCKET"],
    provider="s3",
    region=os.environ["AWS_REGION"],
    secret_provider_id=provider.id,
    access_key_secret="AWS_ACCESS_KEY_ID",
    secret_key_secret="AWS_SECRET_ACCESS_KEY",
)
client.storage.buckets.verify(bucket.id)

sandbox = client.runtime.create(mounts=[{
    "kind": "bucket", "path": "/mnt/data", "bucket": bucket.id, "mode": "rw",
}])
wait_mount(sandbox, "/mnt/data")
print(sandbox.run_cmd("ls", ["/mnt/data"]).stdout)
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const provider = await client.identity.providers.create('aws-creds', {
  secrets: [
    { key: 'AWS_ACCESS_KEY_ID', value: process.env.AWS_ACCESS_KEY_ID! },
    { key: 'AWS_SECRET_ACCESS_KEY', value: process.env.AWS_SECRET_ACCESS_KEY! },
  ],
});
const bucket = await client.storage.buckets.connect('my-s3', process.env.EXTERNAL_BUCKET!, {
  provider: 's3',
  region: process.env.AWS_REGION!,
  secretProviderId: provider.id,
  accessKeySecret: 'AWS_ACCESS_KEY_ID',
  secretKeySecret: 'AWS_SECRET_ACCESS_KEY',
});
await client.storage.buckets.verify(bucket.id);

const sandbox = await client.runtime.create({
  mounts: [{ kind: 'bucket', path: '/mnt/data', bucket: bucket.id, mode: 'rw' }],
});
await waitMount(sandbox, '/mnt/data');
console.log((await sandbox.runCmd('ls /mnt/data')).stdout);
```

```bash CLI theme={null}
PROVIDER_ID=$(gravixlayer provider create aws-creds --type api_key \
  --secret "AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID" \
  --secret "AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY" --output json | jq -r '.id')

BUCKET_ID=$(gravixlayer storage bucket connect my-s3 "$EXTERNAL_BUCKET" \
  --provider s3 --region "$AWS_REGION" \
  --secret-provider-id "$PROVIDER_ID" \
  --access-key-secret AWS_ACCESS_KEY_ID \
  --secret-key-secret AWS_SECRET_ACCESS_KEY \
  --output json | jq -r '.id')
gravixlayer storage bucket verify "$BUCKET_ID"

RT=$(gravixlayer runtime create --wait --output json \
  --mount "{\"kind\":\"bucket\",\"path\":\"/mnt/data\",\"bucket\":\"$BUCKET_ID\",\"mode\":\"rw\"}" \
  | jq -r '.runtime_id')
gravixlayer runtime exec "$RT" -- ls /mnt/data
```

```bash cURL theme={null}
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/buckets" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "my-s3",
    "external": {
      "provider": "s3",
      "bucket": "<your-bucket>",
      "region": "us-east-1",
      "auth_mode": "static",
      "secret_provider_id": "<provider-id>",
      "access_key_secret": "AWS_ACCESS_KEY_ID",
      "secret_key_secret": "AWS_SECRET_ACCESS_KEY"
    }
  }'

curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/buckets/<bucket-id>/verify" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json" \
  -d '{"template":"base-desktop","cloud":"aws","region":"us-east-1","mounts":[{"kind":"bucket","path":"/mnt/data","bucket":"<bucket-id>","mode":"rw"}]}'
```

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"`.

```python Python theme={null}
import os
from gravixlayer import GravixLayer

client = GravixLayer()
provider = client.identity.providers.create(
    "r2-creds",
    secrets=[
        {"key": "ACCESS_KEY_ID", "value": os.environ["R2_ACCESS_KEY_ID"]},
        {"key": "SECRET_ACCESS_KEY", "value": os.environ["R2_SECRET_ACCESS_KEY"]},
    ],
)
bucket = client.storage.buckets.connect(
    "my-r2",
    os.environ["R2_BUCKET"],
    provider="s3_compatible",
    endpoint=os.environ["R2_ENDPOINT"],  # https://<account>.r2.cloudflarestorage.com
    region="auto",
    path_style=True,
    secret_provider_id=provider.id,
    access_key_secret="ACCESS_KEY_ID",
    secret_key_secret="SECRET_ACCESS_KEY",
)
client.storage.buckets.verify(bucket.id)

sandbox = client.runtime.create(mounts=[{
    "kind": "bucket", "path": "/mnt/r2", "bucket": bucket.id, "mode": "rw",
}])
wait_mount(sandbox, "/mnt/r2")
print(sandbox.run_cmd(
    "sh", ["-c", "echo hi > /mnt/r2/hi.txt && cat /mnt/r2/hi.txt"]
).stdout)
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const provider = await client.identity.providers.create('r2-creds', {
  secrets: [
    { key: 'ACCESS_KEY_ID', value: process.env.R2_ACCESS_KEY_ID! },
    { key: 'SECRET_ACCESS_KEY', value: process.env.R2_SECRET_ACCESS_KEY! },
  ],
});
const bucket = await client.storage.buckets.connect('my-r2', process.env.R2_BUCKET!, {
  provider: 's3_compatible',
  endpoint: process.env.R2_ENDPOINT!, // https://<account>.r2.cloudflarestorage.com
  region: 'auto',
  pathStyle: true,
  secretProviderId: provider.id,
  accessKeySecret: 'ACCESS_KEY_ID',
  secretKeySecret: 'SECRET_ACCESS_KEY',
});
await client.storage.buckets.verify(bucket.id);

const sandbox = await client.runtime.create({
  mounts: [{ kind: 'bucket', path: '/mnt/r2', bucket: bucket.id, mode: 'rw' }],
});
await waitMount(sandbox, '/mnt/r2');
console.log(
  (await sandbox.runCmd('echo hi > /mnt/r2/hi.txt && cat /mnt/r2/hi.txt')).stdout,
);
```

```bash CLI theme={null}
PROVIDER_ID=$(gravixlayer provider create r2-creds --type api_key \
  --secret "ACCESS_KEY_ID=$R2_ACCESS_KEY_ID" \
  --secret "SECRET_ACCESS_KEY=$R2_SECRET_ACCESS_KEY" --output json | jq -r '.id')

BUCKET_ID=$(gravixlayer storage bucket connect my-r2 "$R2_BUCKET" \
  --provider s3_compatible \
  --endpoint "$R2_ENDPOINT" --region auto --path-style \
  --secret-provider-id "$PROVIDER_ID" \
  --access-key-secret ACCESS_KEY_ID \
  --secret-key-secret SECRET_ACCESS_KEY \
  --output json | jq -r '.id')
gravixlayer storage bucket verify "$BUCKET_ID"

RT=$(gravixlayer runtime create --wait --output json \
  --mount "{\"kind\":\"bucket\",\"path\":\"/mnt/r2\",\"bucket\":\"$BUCKET_ID\",\"mode\":\"rw\"}" \
  | jq -r '.runtime_id')
gravixlayer runtime exec "$RT" -- sh -c 'echo hi > /mnt/r2/hi.txt && cat /mnt/r2/hi.txt'
```

```bash cURL theme={null}
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/buckets" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "my-r2",
    "external": {
      "provider": "s3_compatible",
      "bucket": "<your-bucket>",
      "endpoint": "https://<account>.r2.cloudflarestorage.com",
      "region": "auto",
      "path_style": true,
      "auth_mode": "static",
      "secret_provider_id": "<provider-id>",
      "access_key_secret": "ACCESS_KEY_ID",
      "secret_key_secret": "SECRET_ACCESS_KEY"
    }
  }'

curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/buckets/<bucket-id>/verify" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json" \
  -d '{"template":"base-desktop","cloud":"aws","region":"us-east-1","mounts":[{"kind":"bucket","path":"/mnt/r2","bucket":"<bucket-id>","mode":"rw"}]}'
```

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.

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
sandbox = client.runtime.create(mounts=[{
    "kind": "git",
    "path": "/mnt/repo",
    "url": "https://github.com/octocat/Hello-World.git",
    "depth": 1,
}])
wait_mount(sandbox, "/mnt/repo")
print(sandbox.run_cmd("ls", ["/mnt/repo"]).stdout)
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create({
  mounts: [{
    kind: 'git',
    path: '/mnt/repo',
    url: 'https://github.com/octocat/Hello-World.git',
    depth: 1,
  }],
});
await waitMount(sandbox, '/mnt/repo');
console.log((await sandbox.runCmd('ls /mnt/repo')).stdout);
```

```bash CLI theme={null}
RT=$(gravixlayer runtime create --wait --output json \
  --mount '{"kind":"git","path":"/mnt/repo","url":"https://github.com/octocat/Hello-World.git","depth":1}' \
  | jq -r '.runtime_id')
gravixlayer runtime exec "$RT" -- ls /mnt/repo
```

```bash cURL theme={null}
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json" \
  -d '{"template":"base-desktop","cloud":"aws","region":"us-east-1","mounts":[{"kind":"git","path":"/mnt/repo","url":"https://github.com/octocat/Hello-World.git","depth":1}]}'
```

## Mount a private Git repository

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

```python Python theme={null}
import os
from gravixlayer import GravixLayer

client = GravixLayer()
provider = client.identity.providers.create(
    "git-creds",
    secrets=[{"key": "GIT_TOKEN", "value": os.environ["GIT_TOKEN"]}],
)
sandbox = client.runtime.create(mounts=[{
    "kind": "git",
    "path": "/mnt/repo",
    "url": os.environ["PRIVATE_REPO"],
    "credential_provider": provider.id,
    "credential_secret": "GIT_TOKEN",
    "depth": 1,
}])
wait_mount(sandbox, "/mnt/repo")
print(sandbox.run_cmd("ls", ["/mnt/repo"]).stdout)
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const provider = await client.identity.providers.create('git-creds', {
  secrets: [{ key: 'GIT_TOKEN', value: process.env.GIT_TOKEN! }],
});
const sandbox = await client.runtime.create({
  mounts: [{
    kind: 'git',
    path: '/mnt/repo',
    url: process.env.PRIVATE_REPO!,
    credentialProvider: provider.id,
    credentialSecret: 'GIT_TOKEN',
    depth: 1,
  }],
});
await waitMount(sandbox, '/mnt/repo');
console.log((await sandbox.runCmd('ls /mnt/repo')).stdout);
```

```bash CLI theme={null}
PROVIDER_ID=$(gravixlayer provider create git-creds --type api_key \
  --secret "GIT_TOKEN=$GIT_TOKEN" --output json | jq -r '.id')

RT=$(gravixlayer runtime create --wait --output json \
  --mount "{\"kind\":\"git\",\"path\":\"/mnt/repo\",\"url\":\"$PRIVATE_REPO\",\"credential_provider\":\"$PROVIDER_ID\",\"credential_secret\":\"GIT_TOKEN\",\"depth\":1}" \
  | jq -r '.runtime_id')
gravixlayer runtime exec "$RT" -- ls /mnt/repo
```

```bash cURL theme={null}
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json" \
  -d '{"template":"base-desktop","cloud":"aws","region":"us-east-1","mounts":[{"kind":"git","path":"/mnt/repo","url":"<https-clone-url>","credential_provider":"<provider-id>","credential_secret":"GIT_TOKEN","depth":1}]}'
```

## Attach and detach on a running runtime

```python Python theme={null}
mount = sandbox.mounts.attach({
    "kind": "bucket", "path": "/mnt/cache", "bucket": "datasets", "mode": "ro",
})
wait_mount(sandbox, "/mnt/cache")
sandbox.mounts.detach(mount.id)
```

```typescript TypeScript theme={null}
const mount = await sandbox.mounts.attach({
  kind: 'bucket', path: '/mnt/cache', bucket: 'datasets', mode: 'ro',
});
await waitMount(sandbox, '/mnt/cache');
await sandbox.mounts.detach(mount.id);
```

```bash CLI theme={null}
ATTACHMENT_ID=$(gravixlayer runtime mounts attach "$RT" \
  --mount '{"kind":"bucket","path":"/mnt/cache","bucket":"datasets","mode":"ro"}' \
  --output json | jq -r '.id')
gravixlayer runtime mounts detach "$RT" "$ATTACHMENT_ID"
```

```bash cURL theme={null}
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/<runtime-id>/mounts" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"bucket","path":"/mnt/cache","bucket":"datasets","mode":"ro"}'

curl -sS -X DELETE "https://api.gravixlayer.ai/v1/agents/runtime/<runtime-id>/mounts/<attachment-id>" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
```

## 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

| Method | Path | What it does |
| - | - | - |
| POST | `/v1/agents/buckets` | Create a managed bucket, or connect one you already own |
| POST | `/v1/agents/buckets/{bucket_id}/verify` | Check that the platform can reach your bucket |
| GET | `/v1/agents/runtime/{runtime_id}/mounts` | List mounts and their state |
| POST | `/v1/agents/runtime/{runtime_id}/mounts` | Attach a mount to a running runtime |
| DELETE | `/v1/agents/runtime/{runtime_id}/mounts/{attachment_id}` | Detach a mount |
| POST | `/v1/agents/runtime` | Create a runtime with mounts |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.