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	Default	Notes
`token`	required	Personal access token. Redacted in snapshots.
`owner`	required	Repo owner (user or org).
`repo`	required	Repo name.
`ref`	`HEAD`	Branch, tag, or commit SHA.
`baseUrl`	`https://api.github.com`	Override for GitHub Enterprise.

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. See listings under fresh.

Mount mode

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

Getting Started

Access

AI Agents

VFS

CLIs

Watch

Runtimes

Node

Browser

Config

Listings under `fresh`

Mount mode

​Node

​Browser

​Config

​Listings under fresh

​Mount mode

Node

Browser

Config

Listings under `fresh`

Mount mode