GitHub - Mirage

GitHubResource exposes a single repository at a ref as a read-only filesystem. Reads stream blobs through the GitHub API. Setup steps for the personal access token live at GitHub Credentials.

Node

pnpm add @struktoai/mirage-node

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

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

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

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

Browser

pnpm add @struktoai/mirage-browser

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

const gh = await GitHubResource.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.