GitHub - Mirage

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.

Mount mode

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