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
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.
Airtable API root; override to point at a fake or proxy.
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.Requests per second per base. Airtable allows 5 and answers a burst with a 30-second penalty.
Authentication
The token needs the scopesdata.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
<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"}, withfieldskeyed 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 arecords.jsonlline is its stdin shape, so an edit pipes straight back:The CLI also reaches what a file cannot: server-side filters (airtable record list --formulaor--view), one record by id (airtable record get) and comments. -
Read limit: a file holding more than
maxReadRecordsrecords ends withFile too large(cat: <path>: File too large) instead of paging for minutes.catandgrepprint each page as it arrives, so the firstmaxReadRecordsrecords 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, sogrep -l x a bstill answers for the files under the cap. Usehead, a view, or raise the cap. -
Order:
records.jsonlfollows 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
falsecheckbox 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.jsonandtable.jsonreport their exact size. Record files have no size until read, which is whatls -landstatshow. - Freshness: records are always read live; listings of bases, tables and views may be cached.
-
Rate limits: requests are spaced to
requestsPerSecondper base. A429that saysRATE_LIMIT_REACHEDis retried after Airtable’s 30-second penalty; a429for 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.grepandrgon one file: afilterByFormulafetches only the records that may match.head -n N: fetches N records, throughmaxRecords, so the first lines of a large table cost one request.
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>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- The name part of a segment is sanitized, the id after the last
__is exact;lsa directory for exact names. - A
records.jsonlline holdsrecord_id,created_timeandfields, keyed by field name;table.jsongives each field’s type. A missing key is an empty cell, afalsecheckbox included. records.jsonlkeeps the API’s order; a view file applies the view’s filter and sort.- A file over
max_read_recordsrecords stops withFile too large;head -n Nfetches just N records. - The
airtableCLI, if installed, adds server-side filters (airtable record list --formulaor--view), one record by id (airtable record get) and comments (airtable comment list).
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.