Skip to main content
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, which takes the same config. Set up the token as in Airtable setup.

Install

Configure

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

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.
string
required
secret
Personal access token (or OAuth access token), sent as Authorization: Bearer.
string[]
Only these bases are listed or readable. Unset shows every base the token can reach.
string
default:"'https://api.airtable.com/v0'"
Airtable API root; override to point at a fake or proxy.
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.
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’s writes also need data.records:write.

Layout

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 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:
    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.
  • 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.
  • 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 an agent reads with Airtable mounted at /<path>.
Virtual FilesystemVFS Layout/<path>
  • 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 VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.