S3 - Mirage

MIRAGE ships S3VFS in two runtimes:

@struktoai/mirage-node, signs requests server-side using @aws-sdk/client-s3.
@struktoai/mirage-browser, stays secret-free: your backend hands out presigned URLs and the browser fetches them with fetch().

Credentials (IAM user, access keys) are created the same way in both runtimes, see AWS S3 Credentials.

Node (server-side)

pnpm add @struktoai/mirage-node

import { MountMode, Workspace } from '@struktoai/mirage-node'
import { S3VFS } from '@struktoai/mirage-node'

const s3 = new S3VFS({
  bucket: process.env.AWS_S3_BUCKET!,
  region: process.env.AWS_DEFAULT_REGION ?? 'us-east-1',
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  // Optional:
  // endpoint: 'http://localhost:9000',  // MinIO
  // forcePathStyle: true,               // For MinIO/R2
  // timeout: 30,
  // proxy: 'http://proxy:8080',
})

const ws = new Workspace({ '/bucket/': s3 }, { mode: MountMode.READ })
const res = await ws.shell('ls /bucket/')
console.log(res.stdoutText)

If ~/.aws/credentials is configured, you can omit accessKeyId/secretAccessKey and the AWS SDK picks up the default profile. Under write: conditional a write carries the version of the file mirage read, and S3 refuses it when the file has changed since. The endpoint decides which writes can be conditioned: AWS’s conditions every write, copy and delete; any other endpoint (or AWS_ENDPOINT_URL_S3/AWS_ENDPOINT_URL) only a write, so mirage refuses what would copy or delete there. An endpoint set only in an AWS profile is not read: give a non-AWS server its endpoint. A browser mount signed by presigned URLs cannot carry a condition, so it cannot declare write: conditional. If the session last saw no file at the path, the write sends If-None-Match: * and fails if someone created the file in the meantime. A conditional single-file move attempts rollback when source deletion is refused. The move still fails and warns if the destination may remain. Cleanup uses the copy’s S3 version or, for a new destination, its ETag. Unversioned overwrites, same-ETag replacements, retried versioned copies, and uncertain delete outcomes limit recovery; inspect both paths after a failure. An absent destination must remain absent until copying. This guard may add one metadata request; cleanup adds one delete and may require s3:DeleteObjectVersion. Directory and cross-mount moves do not use rollback. A directory mv, rm -r or rmdir looks at the directory again when it is done: a file written into it that the command never listed stays, and the command fails with Directory not empty. Under write: conditional, a directory mv that finds a file changed before it could copy it removes nothing from the source; the copies it made stay at the destination. An append or another rewrite that observes a missing file uses create-only commit under either write policy. S3 checks If-None-Match: * at PUT or final multipart completion, so a delayed creation cannot replace a competing writer’s bytes. A lost condition returns an error without automatic retry. Existing-file appends under unconditional retain last-write-wins behavior.

Config

Field	Description
`bucket` required	Name of the bucket to mount.
`region`	AWS region requests are signed for and sent to. Unset leaves it to the AWS SDK’s environment variables and profile.
`endpoint`	Endpoint URL of an S3-compatible server. Unset, the node mount uses `AWS_ENDPOINT_URL_S3` or `AWS_ENDPOINT_URL` when set, else AWS’s endpoint for `region`; an endpoint set only in an AWS profile is not read.
`accessKeyId` secret	Access key ID; set it with `secretAccessKey`. Unset uses the AWS SDK credential chain.
`secretAccessKey` secret	Secret access key paired with `accessKeyId`.
`sessionToken` secret	Session token for temporary credentials, sent with the access key pair.
`forcePathStyle`	Address the bucket in the URL path (`<endpoint>/<bucket>/<key>`) instead of as a subdomain of the endpoint.
`timeout` default `DEFAULT_TIMEOUT`	Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
`presignedUrlProvider` secret	Function `(path, operation, options)` that returns a signed URL for each S3 operation. When set, the mount fetches those URLs and needs no credentials.
`httpAgentProvider` secret	Function that returns the `httpAgent` and `httpsAgent` for one S3 client, called once per client. The node mount builds it from `proxy` when that is set.
`defaultContentType`	`Content-Type` stored with every object the mount writes. Unset sends none, so the store applies its own default; a write through `presignedUrlProvider` sends `application/octet-stream`.
`keyPrefix`	Key prefix inside the bucket that the mount treats as its root; keys outside it are not visible. Leading slashes are dropped and a trailing `/` is added.
`profile`	Named profile in the shared AWS config and credentials files that supplies credentials when no access key pair is given.
`proxy` secret	Proxy URL for every HTTP and HTTPS request to the endpoint.

Fields marked secret are redacted in snapshots.

Browser (presigned URLs)

pnpm add @struktoai/mirage-browser

The browser S3VFS never sees AWS credentials. You implement one function, presignedUrlProvider, that your frontend calls to get a signed URL for each S3 operation. The actual signing happens on your server, using any S3-signing SDK you prefer.

Config

Field	Description
`bucket` required	Name of the bucket to mount.
`region`	AWS region requests are signed for and sent to. Unset leaves it to the AWS SDK’s environment variables and profile.
`endpoint`	Endpoint URL of an S3-compatible server. Unset, the node mount uses `AWS_ENDPOINT_URL_S3` or `AWS_ENDPOINT_URL` when set, else AWS’s endpoint for `region`; an endpoint set only in an AWS profile is not read.
`timeout` default `DEFAULT_TIMEOUT`	Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
`presignedUrlProvider` secret	Function `(path, operation, options)` that returns a signed URL for each S3 operation. When set, the mount fetches those URLs and needs no credentials.
`defaultContentType`	`Content-Type` stored with every object the mount writes. Unset sends none, so the store applies its own default; a write through `presignedUrlProvider` sends `application/octet-stream`.
`keyPrefix`	Key prefix inside the bucket that the mount treats as its root; keys outside it are not visible. Leading slashes are dropped and a trailing `/` is added.

Fields marked secret are redacted in snapshots. The browser S3VFS can also sign requests itself, without presignedUrlProvider: it then takes the credential fields of the Node config, which puts the keys in the browser.

1. Server: sign URLs on demand

Using @aws-sdk/s3-request-presigner:

import {
  CopyObjectCommand,
  DeleteObjectCommand,
  GetObjectCommand,
  HeadObjectCommand,
  ListObjectsV2Command,
  PutObjectCommand,
  S3Client,
} from '@aws-sdk/client-s3'
import { getSignedUrl } from '@aws-sdk/s3-request-presigner'

const client = new S3Client({ region: process.env.AWS_DEFAULT_REGION })
const BUCKET = process.env.AWS_S3_BUCKET!

app.post('/presign', async (req, res) => {
  const { path, op, opts } = req.body as {
    path: string
    op: 'GET' | 'PUT' | 'HEAD' | 'DELETE' | 'LIST' | 'COPY'
    opts?: Record<string, unknown>
  }
  const key = path.replace(/^\/+/, '')
  const ttl = typeof opts?.ttlSec === 'number' ? opts.ttlSec : 300
  let cmd
  switch (op) {
    case 'GET':    cmd = new GetObjectCommand({ Bucket: BUCKET, Key: key }); break
    case 'PUT':    cmd = new PutObjectCommand({ Bucket: BUCKET, Key: key, ContentType: opts?.contentType as string | undefined }); break
    case 'HEAD':   cmd = new HeadObjectCommand({ Bucket: BUCKET, Key: key }); break
    case 'DELETE': cmd = new DeleteObjectCommand({ Bucket: BUCKET, Key: key }); break
    case 'LIST':   cmd = new ListObjectsV2Command({
      Bucket: BUCKET,
      Prefix: opts?.listPrefix as string | undefined,
      Delimiter: opts?.listDelimiter as string | undefined,
      ContinuationToken: opts?.listContinuationToken as string | undefined,
    }); break
    case 'COPY':   cmd = new CopyObjectCommand({
      Bucket: BUCKET,
      Key: key,
      CopySource: `${BUCKET}/${opts?.copySource as string}`,
    }); break
  }
  const url = await getSignedUrl(client, cmd, { expiresIn: ttl })
  res.json({ url })
})

Scope the presigner to the minimal operations your app needs. Read-only viewers only need GET/HEAD/LIST; a file manager needs the full set.

2. Browser: wire it up

import { MountMode, S3VFS, Workspace } from '@struktoai/mirage-browser'

const s3 = new S3VFS({
  bucket: 'my-bucket',
  presignedUrlProvider: async (path, op, opts) => {
    const r = await fetch('/presign', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ path, op, opts }),
    })
    const { url } = (await r.json()) as { url: string }
    return url
  },
})

const ws = new Workspace({ '/bucket/': s3 }, { mode: MountMode.READ })
const res = await ws.shell('cat /bucket/hello.txt')
console.log(res.stdoutText)

Customize a builtin command

The generic command definitions are available before a workspace is created. Copy the definition with the behavior you want to change, then register that copy on one mount:

import { generic } from '@struktoai/mirage-browser'

const cat = generic('cat')

ws.mount('/bucket/')?.register({
  ...cat,
  fn: async (accessor, paths, texts, opts) => {
    console.log('reading', paths.map((path) => path.virtual))
    return cat.fn(accessor, paths, texts, opts)
  },
})

Use the same generic export from @struktoai/mirage-node for a Node workspace. The builtin definition and other mounts stay unchanged. Registration is a host application action; an agent can discover and run the resulting cat command, but cannot alter the command table.

3. Configure CORS on the bucket

Presigned URLs reach the S3 host directly from the browser. Your bucket must allow cross-origin requests from your app’s origin, otherwise every fetch() fails with TypeError: Failed to fetch (the browser drops the response at the CORS preflight).

[
  {
    "AllowedOrigins": ["http://localhost:5173", "https://app.example.com"],
    "AllowedMethods": ["GET", "PUT", "HEAD", "DELETE", "POST"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag", "Content-Length", "Content-Type", "Last-Modified"],
    "MaxAgeSeconds": 3000
  }
]

aws s3api put-bucket-cors --bucket $AWS_S3_BUCKET --cors-configuration file://cors.json

Or use the helper in the browser example, it signs the PutBucketCors call with your existing env credentials and applies the same policy to all configured buckets in one shot:

cd examples/browser
npx tsx scripts/configure-cors.ts http://localhost:5173 https://app.example.com

CORS is origin-exact. http://localhost:5173 ≠ http://localhost:5174 ≠ https://app.example.com. Include every origin you’ll serve the page from.

See S3 Setup for credential setup.

Refused keys

When credentials cannot read an S3 object (S3 returns AccessDenied, or a bodiless HTTP 403 response on a HEAD request), Mirage reports EACCES (Permission denied) for that file operand. Shell commands follow standard POSIX conventions:

cat a b c prints the contents of a and c, writes a permission error for b to stderr, and exits with a non-zero status.
grep -r logs an error on inaccessible files and exits with status 2.
cp b x || fallback triggers the fallback branch.
test -e b evaluates to false.

IAM permissions and existence checks

Scoped grants: When access is granted below a specific prefix (for example, s3:GetObject on bucket/dir/* alongside s3:ListBucket on the bucket), Mirage treats dir as a directory during stat.
Missing ListBucket: Without s3:ListBucket permission, S3 returns HTTP 403 even for non-existent keys to avoid leaking existence. As a result, non-existent files report Permission denied (EACCES) instead of No such file or directory (ENOENT).
Listed but unreadable keys: If ListObjectsV2 includes an object that your credentials cannot read, stat and test -e report that the file exists, while read attempts (cat) fail with Permission denied.
Browser presigned URLs: Mirage does not parse the HTTP error body when reading through presigned URLs in the browser. Any HTTP 403 status (including expired or misconfigured URLs) is handled as a permission refusal.

Scoping a VFS to a key prefix

Pass keyPrefix to scope every operation to a subpath of the bucket:

const s3 = new S3VFS({
  bucket: 'app-data',
  region: 'eu-west-1',
  keyPrefix: `users/${userId}/`,
})

When set, every read/write/list/stat/copy/rename/delete operation is transparently scoped to that bucket subpath. Agents see clean paths like /data/notes.md; the underlying bucket key is users/${userId}/data/notes.md. Useful for multi-tenant systems. Pairs naturally with STS AssumeRole session policies for AWS-side enforcement. Unset behavior is unchanged. Normalization: leading slashes are stripped and a trailing slash is added automatically. Both undefined and an empty string are treated as “no prefix.” In YAML-based configs the snake-case spelling key_prefix is also accepted and is automatically mapped to keyPrefix at construction.

Browser variant — security noteFor mirage-browser’s S3VFS (which uses presignedUrlProvider), keyPrefix flows through the same core code path, but a client-controlled prefix is not a security boundary — a malicious client can ignore or alter it before signing. For real isolation, enforce the prefix inside your server-side presignedUrlProvider implementation (and in the IAM/STS session policy backing those credentials). Treat the client-side keyPrefix as ergonomics only.

VFS.md

The VFS.md an agent reads with S3 mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`s3`, write

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Almost all Unix commands.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	`grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `s3`, write |

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Almost all Unix commands. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

Integration

What S3 answers through its own API, so fewer files are read. Integration explains each command.

Command	On S3
`md5sum`	The object’s ETag, when it is the MD5: a single-part upload, unencrypted or under SSE-S3
`find`, `du`, `ls -R`, `tree`	One recursive listing

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

S3

Node (server-side)

Config

Browser (presigned URLs)

Config

1. Server: sign URLs on demand

2. Browser: wire it up

Customize a builtin command

3. Configure CORS on the bucket

Refused keys

IAM permissions and existence checks

Scoping a VFS to a key prefix

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​Node (server-side)

​Config

​Browser (presigned URLs)

​Config

​1. Server: sign URLs on demand

​2. Browser: wire it up

​Customize a builtin command

​3. Configure CORS on the bucket

​Refused keys

​IAM permissions and existence checks

​Scoping a VFS to a key prefix

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

Node (server-side)

Config

Browser (presigned URLs)

Config

1. Server: sign URLs on demand

2. Browser: wire it up

Customize a builtin command

3. Configure CORS on the bucket

Refused keys

IAM permissions and existence checks

Scoping a VFS to a key prefix

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration