# File Systems

## Host Directory

Project a real host directory into the VM, Docker-style. The guest sees only the mounted subtree, never the wider host filesystem.

| Category | Status | Docs |
| --- | --- | --- |
| File System | Built in | [Guide](/agentos/docs/filesystem) |

### Configuration

Built into the SDK, with no separate install. Enable it in your VM config.

```ts
import { agentOS, setup } from "@rivet-dev/agentos";
import pi from "@agentos-software/pi";

const vm = agentOS({
  software: [pi],
  mounts: [
    {
      path: "/home/agentos/repo",
      plugin: { id: "host_dir", config: { hostPath: "/path/to/repo" } },
      readOnly: true,
    },
  ],
});

export const registry = setup({ use: { vm } });
```

## S3

Mount an S3-compatible bucket as a filesystem. File contents are chunked into S3 objects, keeping large files, partial reads/writes, and snapshots efficient.

| Category | Status | Docs |
| --- | --- | --- |
| File System | Built in | [Guide](/agentos/docs/filesystem) |

### Configuration

Built into the SDK, with no separate install. Enable it in your VM config.

```ts
import { agentOS, setup } from "@rivet-dev/agentos";
import pi from "@agentos-software/pi";

const vm = agentOS({
  software: [pi],
  mounts: [
    {
      path: "/home/agentos/data",
      plugin: {
        id: "s3",
        config: { bucket: "my-bucket", prefix: "agent-data/", region: "us-east-1" },
      },
    },
  ],
});

export const registry = setup({ use: { vm } });
```

## Google Drive

Mount a Google Drive folder as a filesystem for reading and writing documents and files.

| Category | Status | Docs |
| --- | --- | --- |
| File System | Built in | [Guide](/agentos/docs/filesystem) |

### Configuration

Built into the SDK, with no separate install. Enable it in your VM config.

```ts
import { agentOS, setup } from "@rivet-dev/agentos";
import pi from "@agentos-software/pi";

const vm = agentOS({
  software: [pi],
  mounts: [
    {
      path: "/home/agentos/drive",
      plugin: {
        id: "google_drive",
        config: {
          credentials: {
            clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
            privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY!,
          },
          folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
        },
      },
    },
  ],
});

export const registry = setup({ use: { vm } });
```

## In-Memory

Mount an ephemeral in-memory directory. Fast scratch space that is discarded when the VM is destroyed.

| Category | Status | Docs |
| --- | --- | --- |
| File System | Built in | [Guide](/agentos/docs/filesystem) |

### Configuration

Built into the SDK, with no separate install. Enable it in your VM config.

```ts
import { agentOS, setup } from "@rivet-dev/agentos";
import pi from "@agentos-software/pi";

const vm = agentOS({
  software: [pi],
  mounts: [
    // Ephemeral scratch space for large intermediate artifacts (build
    // output, downloads, caches). Lives in memory only: it never touches
    // the VM's persisted filesystem, so it stays out of snapshots and is
    // discarded when the VM is disposed.
    { path: "/tmp/scratch", plugin: { id: "memory", config: {} } },
  ],
});

export const registry = setup({ use: { vm } });
```

## Sandbox

Mount a sandbox filesystem and expose process management bindings. Works with any Sandbox Agent provider.

| Category | Status | Package | Docs |
| --- | --- | --- | --- |
| Bindings, File System | Available | [`@rivet-dev/agentos-sandbox`](https://www.npmjs.com/package/@rivet-dev/agentos-sandbox) | [Guide](/agentos/docs/sandboxes) |

### Install

```sh
npm install @rivet-dev/agentos-sandbox sandbox-agent
```

### Add to agentOS

Mount the sandbox filesystem and register the process bindings with @rivet-dev/agentos-sandbox.

```ts
import { agentOS, setup } from "@rivet-dev/agentos";
import { createSandboxFs, createSandboxBindings } from "@rivet-dev/agentos-sandbox";
import { SandboxAgent } from "sandbox-agent";
import { docker } from "sandbox-agent/docker";

// Mount the sandbox filesystem and expose its process bindings to the VM
const sandbox = await SandboxAgent.start({ sandbox: docker() });

const vm = agentOS({
  mounts: [{ path: "/home/agentos/sandbox", plugin: createSandboxFs({ client: sandbox }) }],
  bindings: [createSandboxBindings({ client: sandbox })],
});

export const registry = setup({ use: { vm } });
```