Airtable

AirtableVFS exposes the bases a personal access token can reach as a read-only tree of tables, records, and saved views. Reads go through the Airtable Web API with plain fetch, so one class serves Node and the browser. Setup steps for the token live at Airtable Credentials.

Node

pnpm add @struktoai/mirage-node

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

const airtable = new AirtableVFS({ token: process.env.AIRTABLE_TOKEN! })

const ws = new Workspace({ '/airtable': airtable }, { mode: MountMode.READ })
await ws.shell('ls /airtable/bases/')

Browser

pnpm add @struktoai/mirage-browser

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

const airtable = new AirtableVFS({ token: AIRTABLE_TOKEN })

The Airtable API sends access-control-allow-origin: *, so the browser calls it directly; a token in a page is visible to that page’s user.

Config

Field	Description
`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.
`token` required, secret	Personal access token (or OAuth access token), sent as `Authorization: Bearer`.
`baseIds`	Only these bases are listed or readable. Unset shows every base the token can reach.
`baseUrl` default `'https://api.airtable.com/v0'`	Airtable API root; override to point at a fake or proxy.
`maxReadRecords` default `10000`	The most records one file renders. A full read of a larger table or view fails with `File too large` once it passes the cap; `head -n N` still reads its first records.
`requestsPerSecond` default `5`	Requests per second per base. Airtable allows 5 and answers a burst with a 30-second penalty.

Fields marked secret are redacted in snapshots.

Mount mode

read. Writes go through the airtable CLI, which takes the same config and names a base, a table and a record by the id after the last __ of the mount’s directory names. For the mounted layout (bases/, table.json, records.jsonl, views/) and the reading rules see the Python Airtable docs.

VFS.md

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

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`airtable`, read

VFS Layout

`/<path>`

/<path>
  bases/
    <base-name>__<base-id>/
      base.json                         # base id, name, permission, tables
      <table-name>__<table-id>/
        table.json                      # typed fields (with options), views
        records.jsonl                   # one record per line
        views/
          <view-name>__<view-id>.jsonl  # records the view shows, in order

ls a directory first to find exact names: the name part of a segment is sanitized, the id after the last __ is exact.
A records.jsonl line is a normalized record: record_id, created_time and fields, keyed by field name with values as Airtable returns them. table.json gives each field’s type.
Airtable omits empty cells, so a missing key means empty, a false checkbox included. A link field is a list of record ids; an attachment URL expires two hours after it was read.
records.jsonl lists in the API’s own order; a view file applies the view’s filter and sort.
A file over max_read_records records stops with File too large after that many, while head -n N fetches just N records.
The airtable CLI, if installed, reaches what a file cannot: server-side filters (airtable record list --formula or --view), one record by id (airtable record get) and comments (airtable comment list).

head -n 20 /<path>/bases/<base>/<table>/records.jsonl | jq .fields

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>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep` and `rg` ask `airtable` for the matching lines. `head` asks `airtable` instead of reading a file.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `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>` | `airtable`, read |

## VFS Layout

### `/<path>`

```text
/<path>
  bases/
    <base-name>__<base-id>/
      base.json                         # base id, name, permission, tables
      <table-name>__<table-id>/
        table.json                      # typed fields (with options), views
        records.jsonl                   # one record per line
        views/
          <view-name>__<view-id>.jsonl  # records the view shows, in order
```

- `ls` a directory first to find exact names: the name part of a segment
  is sanitized, the id after the last `__` is exact.
- A `records.jsonl` line is a normalized record: `record_id`,
  `created_time` and `fields`, keyed by field name with values as
  Airtable returns them. `table.json` gives each field's type.
- Airtable omits empty cells, so a missing key means empty, a `false`
  checkbox included. A link field is a list of record ids; an attachment
  URL expires two hours after it was read.
- `records.jsonl` lists in the API's own order; a view file applies the
  view's filter and sort.
- A file over `max_read_records` records stops with `File too large`
  after that many, while `head -n N` fetches just N records.
- The `airtable` CLI, if installed, reaches what a file cannot:
  server-side filters (`airtable record list --formula` or `--view`), one
  record by id (`airtable record get`) and comments
  (`airtable comment list`).

```sh
head -n 20 /<path>/bases/<base>/<table>/records.jsonl | jq .fields
```

## 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>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep` and `rg` ask `airtable` for the matching lines. `head` asks `airtable` instead of reading a file. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `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 Airtable answers through its own API, so fewer files are read. Integration explains each command.

Command	On Airtable
`grep`, `rg` on one file	A `filterByFormula` fetches only the records that may match
`head -n N`	Fetches N records

The Python Airtable docs list when each search answers and what it can miss.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​Node

​Browser

​Config

​Mount mode

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration