GitHub

GitHubVFS exposes a single repository at a ref as a read-only filesystem. Reads stream blobs through GitHub’s REST API; it does not imitate another CLI. Setup steps for the personal access token live at GitHub Credentials.

Node

pnpm add @struktoai/mirage-node

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

const gh = await GitHubVFS.create({
  token: process.env.GITHUB_TOKEN!,
  owner: 'strukto-ai',
  repo: 'mirage',
  ref: 'main',
})

const ws = new Workspace({ '/repo': gh }, { mode: MountMode.READ })
await ws.shell('cat /repo/README.md')

The constructor is private: create fetches the repo’s git tree before it builds the VFS, so it has to be awaited. Python deliberately differs here: GitHubVFS(...) is an ordinary call that contacts nothing, and hydrates the tree on first read, which is what lets its build_vfs stay synchronous.

Browser

pnpm add @struktoai/mirage-browser

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

const gh = await GitHubVFS.create({
  token: GITHUB_TOKEN,
  owner: 'strukto-ai',
  repo: 'mirage',
})

The token reaches the browser, so use a fine-grained PAT scoped to read-only access on a single repo.

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	GitHub personal access token.
`owner` required	Repository owner, a user or an organization.
`repo` required	Repository name.
`ref`	Branch, tag or commit SHA the mount reads. Unset uses the repository’s default branch, resolved when the mount is created.
`baseUrl` default `'https://api.github.com'`	GitHub API root; set it for GitHub Enterprise.

Fields marked secret are redacted in snapshots.

Listings under `fresh`

Under read: fresh, a cached listing is checked against the head commit the ref resolves to: one small check per command (a shallow git/trees/{ref}), after which every cached listing of the mount at that commit is served. A mount whose ref is a full 40- or 64-hex commit sha serves its cached listings with no request: github.com refuses a branch or tag named with 40 or 64 hex characters, so such a ref always names a commit (a GitHub Enterprise host is assumed to do the same). A repository whose recursive tree comes back truncated stores no version, so each folder is re-listed once per command.

Mount mode

read. Writes are not yet exposed. For the mounted layout (refs, paths, blob caching) see the Python GitHub docs.

Integration

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

Command	On GitHub
`grep -r`, `rg`	GitHub code search, for whole words, on the default branch, under a path with more than 100 files. It can miss recent pushes.
`find`, `du`, `ls -R`, `tree`	One recursive tree listing

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

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Browser

Config

Listings under `fresh`

Mount mode

Integration

​Node

​Browser

​Config

​Listings under fresh

​Mount mode

​Integration

Node

Browser

Config

Listings under `fresh`

Mount mode

Integration