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

# Airtable

> Virtualize Airtable bases from Node or the browser.

`AirtableVFS` turns the bases a personal access token can reach into a
read-only tree: every table holds its field schema, its records as JSON lines
and one file per saved view. Writes go through the
[airtable CLI](https://docs.mirage.strukto.ai/typescript/cli/airtable.md), which takes the same config. Set up the token as in [Airtable setup](https://docs.mirage.strukto.ai/home/setup/airtable.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
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 })

const result = await ws.shell('ls /airtable/bases')
console.log(result.stdoutText)
await ws.close()
```

`baseIds` limits the mount to those bases, and `maxReadRecords` bounds a full read
of one file. Unknown keys are refused, so a misspelled `baseIds` fails loudly
instead of widening the mount to every base.

### Fields

**timeout** `number` (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** `string` *required*

Personal access token (or OAuth access token), sent as `Authorization: Bearer`.

**baseIds** `string[]`

Only these bases are listed or readable. Unset shows every base the token can reach.

**baseUrl** `string` (default: '[https://api.airtable.com/v0](https://api.airtable.com/v0)')

Airtable API root; override to point at a fake or proxy.

**maxReadRecords** `number` (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** `number` (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.

## Authentication

The token needs the scopes `data.records:read` and `schema.bases:read`; without
`schema.bases:read` it cannot list tables. Only the bases (or workspaces) under
the token's **Access** are visible: a base left out reads as if it did not
exist. The [airtable CLI](https://docs.mirage.strukto.ai/typescript/cli/airtable.md)'s writes also need `data.records:write`.

## Layout

```text theme={null}
/airtable/
  bases/
    Product_Roadmap__appRoadmapBase001/
      base.json
      Features__tblFeatures000001/
        table.json
        records.jsonl
        views/
          Done_shipped__viwDone0000000001.jsonl
```

Each folder is `<name>__<id>`. Names are sanitized (`Ops / Finance` becomes
`Ops_Finance`); the id after the last `__` is exact. List a folder to find
names rather than building them.

* `base.json`: the base id, name, the token's permission level and the tables.
* `table.json`: the typed field schema, with each field's options (select
  choices, number precision, link targets), and the saved views.
* `records.jsonl`: one record per line, `{"record_id", "created_time",
  "fields"}`, with `fields` keyed by field name and valued exactly as Airtable
  returns them.
* `views/<view>.jsonl`: the records the view shows, filtered and ordered by
  the view.

## Behavior

* **Read-only:** a record write is not a file write, so the mount refuses it.
  The [airtable CLI](https://docs.mirage.strukto.ai/typescript/cli/airtable.md) names a base, a table and a record by the id after
  the last `__` of the mount's folder names, and a `records.jsonl` line is its
  stdin shape, so an edit pipes straight back:

  ```bash theme={null}
  jq -c 'select(.fields.Status == "Todo") | .fields.Status = "Done"' \
    /airtable/bases/Product_Roadmap__appRoadmapBase001/Features__tblFeatures000001/records.jsonl \
    | airtable record update --base appRoadmapBase001 --table tblFeatures000001
  ```

  The CLI also reaches what a file cannot: server-side filters
  (`airtable record list --formula` or `--view`), one record by id
  (`airtable record get`) and comments.
* **Read limit:** a file holding more than `maxReadRecords` records ends with
  `File too large` (`cat: <path>: File too large`) instead of paging for
  minutes. `cat` and `grep` print each page as it arrives, so the first
  `maxReadRecords` records come before the error, and a reader that stops first
  (`head -c 100`, `grep -l`) never reaches it. Every command reports it per
  file and moves on, so `grep -l x a b` still answers for the files under the
  cap. Use `head`, a view, or raise the cap.
* **Order:** `records.jsonl` follows the API's own order, which Airtable calls
  arbitrary but keeps stable; a view file applies the view's sort.
* **Empty cells:** Airtable omits empty values from a record, a `false`
  checkbox included, so a missing key means empty.
* **Links and attachments:** a linked-record field is a list of record ids. An
  attachment URL expires two hours after it was read, so re-read the record
  before downloading.
* **Sizes:** `base.json` and `table.json` report their exact size. Record files
  have no size until read, which is what `ls -l` and `stat` show.
* **Freshness:** records are always read live; listings of bases, tables and
  views may be cached.
* **Rate limits:** requests are spaced to `requestsPerSecond` per base. A `429` that says
  `RATE_LIMIT_REACHED` is retried after Airtable's 30-second penalty; a `429`
  for an exhausted monthly quota is reported at once, since waiting cannot fix
  it.

## Browser

`@struktoai/mirage-browser` exports the same `AirtableVFS`. The Airtable API
sends `access-control-allow-origin: *`, so the page calls it directly.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { AirtableVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const airtable = new AirtableVFS({ token: AIRTABLE_TOKEN })
const ws = new Workspace({ '/airtable': airtable }, { mode: MountMode.READ })
```

* A token in a page is visible to that page's user.

## Integration

Airtable answers these commands through its own API, so fewer records are
read. See [Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep` and `rg` on one file: a `filterByFormula` fetches only the records
  that may match.
* `head -n N`: fetches N records, through `maxRecords`, so the first lines of
  a large table cost one request.

For one plain text in a `records.jsonl` or a view's file, the formula searches
the record id and each text, select, email, url and phone cell, lowercased, in
the order a plain read lists them. Number, date and checkbox cells hold no word
to search. A link, AI text or attachment cell holds no space outside the text a
formula reads of it, so a table with one is searched for a text with a space
and read for a single word. The file is read as usual for a table with a
collaborator, lookup, rollup or formula field, for a text a field name holds,
or when more than `maxReadRecords` records match. A table too large to read
can still be searched when the output shows no line numbers or context.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Airtable mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `airtable`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<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
> ```
>
> * The name part of a segment is sanitized, the id after the last `__` is
>   exact; `ls` a directory for exact names.
> * A `records.jsonl` line holds `record_id`, `created_time` and `fields`,
>   keyed by field name; `table.json` gives each field's type. A missing
>   key is an empty cell, a `false` checkbox included.
> * `records.jsonl` keeps the API's order; a view file applies the view's
>   filter and sort.
> * A file over `max_read_records` records stops with `File too large`;
>   `head -n N` fetches just N records.
> * The `airtable` CLI, if installed, adds server-side filters
>   (`airtable record list --formula` or `--view`), one record by id
>   (`airtable record get`) and comments (`airtable comment list`).
>
> **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.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> 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
> ```
>
> - The name part of a segment is sanitized, the id after the last `__` is
>   exact; `ls` a directory for exact names.
> - A `records.jsonl` line holds `record_id`, `created_time` and `fields`,
>   keyed by field name; `table.json` gives each field's type. A missing
>   key is an empty cell, a `false` checkbox included.
> - `records.jsonl` keeps the API's order; a view file applies the view's
>   filter and sort.
> - A file over `max_read_records` records stops with `File too large`;
>   `head -n N` fetches just N records.
> - The `airtable` CLI, if installed, adds server-side filters
>   (`airtable record list --formula` or `--view`), one record by id
>   (`airtable record get`) and comments (`airtable comment list`).
>
> ## 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.
> ````


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