The repository's dev container provides a Linux development machine for the Rust CLIs, Python bindings and browser viewer. The same checkout works from a terminal, VS Code, Codex or Claude Code. Each assistant has its own account sign-in, permissions and chat history.
- Check your personal Codespaces usage and enforced budget. Included compute and storage are shared by all your Codespaces. GitHub Pro includes 180 core-hours (90 hours on a two-core machine) and 20 GB-month of storage; Free includes 120 core-hours and 15 GB-month. Stopped machines still consume storage. Public repositories do not receive unlimited Codespaces compute. GitHub Actions billing is separate.
- Open the repository's Code → Codespaces → New with options. Select
the branch containing this configuration, the
rvt-rsdev container, and 2 cores / 8 GB. Do not create a replacement for a peer's machine. - Wait for the post-create command to finish. It installs Codex, Claude
Code and the
viewer/package.jsonpnpm version from.devcontainer/tools/package-lock.json, stable Rust, Python 3.12 from Ubuntu 24.04, and Chromium. It reuses.cursor/install.shto build the native tools, Python binding and WASM viewer, then exercises a generated fixture through the CLI and browser.
The native build uses profile.ci (no release LTO); WASM uses --dev.
Cargo and Rayon default to two jobs in the container and SSH login shell.
Node's feature installs npm 12.2.0; pnpm comes only from the repository pin,
and provision.sh refuses a lock whose pnpm is not viewer/package.json's.
The tools' lock pins every dependency by hash and is installed with
npm ci; its allowScripts lets only Claude Code's and pnpm's install
scripts run. CI's env config lint job runs provision.sh on every pull
request, and Dependabot updates the lock (pnpm by hand, with the
packageManager).
The wasm-pack 0.14.0 pin and Python hash-locked requirements remain shared
with Cursor setup. No corpus downloads, prebuild fleet or unit tests run.
The image digest and the tools' lock are deliberate reproducibility pins;
Dependabot proposes their updates, and a refresh is checked by a remote
invocation when maintaining the image.
Features track their official major release; Rust tracks stable and Node 24
tracks its supported patch releases. Record the actual versions in evidence.
Post-create logs, CLI outputs and a browser screenshot are under
/workspaces/.rvt-rs-evidence/rvt-rs/create-<timestamp>-<pid>/.
Failures preserve their logs and fail setup. To inspect one, use less or
sed -n '1,160p' <log>. A resume only checks the environment and binding;
it does not reinstall, rebuild or start a server.
Bootstrap output is also recorded directly in the visible creation terminal,
with the command's exit status preserved.
On the computer running your desktop apps, authenticate GitHub CLI with
the codespace scope, then select the specific rvt-rs machine:
gh auth refresh -h github.com -s codespace
gh codespace list --repo DrunkOnJava/rvt-rs
gh codespace ssh -c YOUR_RVT_CODESPACEInside it, the checkout is /workspaces/rvt-rs. Use normal Git branches;
push source before stopping. To generate OpenSSH entries locally:
gh codespace ssh --config -c YOUR_RVT_CODESPACE > ~/.ssh/rvt-codespacesAdd Include ~/.ssh/rvt-codespaces to ~/.ssh/config before general
Host * defaults, preserving existing entries. Use the concrete Host
alias generated by GitHub in ssh ALIAS; keep its ProxyCommand and key
settings intact. The container includes sshd and SFTP for desktop clients.
Do not expose sshd or an assistant app server as a public forwarded port.
| Client | Entry point | Authentication and verification |
|---|---|---|
| Codex / ChatGPT desktop | Settings → Connections → SSH; enable the concrete OpenSSH alias, then add /workspaces/rvt-rs |
Run codex login on the remote machine using the subscription sign-in flow. Verify bash -lc 'command -v codex; codex login status' over SSH before connecting. The app starts the remote Codex server through the login shell. |
| Claude desktop Code tab | Environment selector → SSH connection; use the same OpenSSH alias and checkout | macOS/Linux desktop versions with OpenSSH support honor ProxyCommand. SFTP and multiple SSH sessions are required. Desktop installs its own remote helper. Verify this route in the app; a working CLI alone does not prove it. |
| Claude Code terminal | claude in the remote checkout |
Sign in to the intended subscription independently. Never set an API key as an automatic fallback. |
| VS Code desktop | Codespaces extension → Connect to Codespace; or gh codespace code -c YOUR_RVT_CODESPACE |
GitHub sign-in is separate from either assistant. The Rust/Python/Claude extensions are recommended in the container. |
| Browser | Open the machine from GitHub Codespaces | Browser VS Code is also available; it does not transfer local Chrome sign-ins or native desktop apps. |
| JupyterLab | Codespaces → Open in JupyterLab, or gh codespace jupyter -c YOUR_RVT_CODESPACE |
Uses the hash-locked project .venv; select rvt-rs (Python 3.12). The VS Code Jupyter extension alone does not install this server. |
Codex's Work in → Cloud uses OpenAI's environment service. This Codespace is an SSH remote project. Verify the remote host and checkout in a chat before claiming desktop setup is complete. Starting another assistant session or selecting a different provider/model needs its own authorization.
AGENTS.md is the shared public repository instruction source. The first
create writes a local, gitignored CLAUDE.md that imports it. Keep personal hooks, credentials and Mac paths out of
the image and public repository. Do not copy .ssh, .codex or .claude
trees from a personal computer. Sign-ins in the container home generally
survive stop/start, but a rebuild can replace that home; sign in again if
needed. Do not persist credentials by writing them into /workspaces or
committing them. Use repository-scoped Codespaces secrets only when needed.
cd /workspaces/rvt-rs
cargo build --locked --profile ci
.venv/bin/maturin develop --locked --manifest-path rvt-py/Cargo.toml --profile ci
wasm-pack build rvt-wasm --dev --target web --out-dir ../viewer/pkg --out-name rvt -- --locked
(cd viewer && pnpm run build)
bash .devcontainer/resume.sh
bash .devcontainer/verify.sh
tools/ci/verify-real-files.sh --profile ci
cd viewer
CI=1 pnpm exec playwright test --config playwright.config.ts --workers=1
pnpm run dev --host 0.0.0.0Port 5173 is forwarded privately. Confirm its visibility in the Ports
panel before opening it. Browser checks bind preview port 4173 to loopback.
Use gh codespace ports forward 5173:5173 -c YOUR_RVT_CODESPACE for local
access without making it public. Stop the foreground server with Ctrl-C.
verify.sh exercises what is already built and rebuilds nothing: it fails when
the CLI, the Python binding, the WASM package or the viewer bundle is older than
a source file,
so rebuild all three first, as above or with the rvt: smoke task.
The smoke script saves viewer-smoke.png, browser.json, the exact source
SHA, CLI output, IFC and diagnostics. Open the screenshot for visual review.
Each smoke invocation chooses a new evidence directory. An explicit directory
is also accepted, but an existing verify.log is never overwritten.
Synthetic fixtures prove parser/scaffold paths, not real Revit geometry.
External corpora are opt-in; follow corpus intake and
corpus sources. Do not copy private oracle material.
Linux Codespaces cannot supply Revit-hosted Windows oracle execution.
The account's default editor can route a Codespaces link to JupyterLab.
Use Open in Visual Studio Code for the browser editor instead; changing
that account-wide preference also affects your other Codespaces. JupyterLab
is installed by .devcontainer/notebooks.sh during first-create. To add it
to a machine created before this setup, run that script once. The registered
kernel uses the same .venv as the editable Rust/Python binding. Open
codespaces.ipynb for a synthetic-file example. Notebook
port 8888 stays private; GitHub manages the JupyterLab entry connection.
VS Code reads shared repository settings from .vscode/settings.json.
Terminal → Run Task exposes these workflows:
| Task | Result |
|---|---|
rvt: build |
Native tools in target/ci; default build shortcut |
rvt: clippy, rvt: format check |
Explicit compiler/lint and formatting checks |
rvt: Python binding |
Rebuild the editable extension in .venv |
rvt: WASM, viewer: build |
WASM, then the typechecked static viewer |
viewer: dev |
Vite on private forwarded port 5173; stop with Terminate Task |
rvt: smoke |
Build all three components, then save CLI/Python/browser evidence |
rvt: verify real files |
Repository integration/CLI/contract checks; unit targets excluded |
viewer: browser checks |
Existing headless browser suite with one worker |
Run and Debug offers Debug rvt-inspect, which builds a separate native debug
binary with line information and prompts for a remote fixture path. Python: current file uses the selected .venv interpreter. Generated output is
excluded from file watching/search, Rust formatting is enabled on save, and
automatic compiler checks and Python unit-test discovery are disabled to keep
the two-core machine responsive. Manual check tasks remain available.
GitHub Codespaces ownership, Git push credentials, editor Accounts, Settings
Sync, Copilot chat, Codex and Claude are separate connections. Inspect the
editor's Accounts menu to identify its GitHub session. A chat Sign In
button can refer to Copilot rather than repository access. Sign in to an
existing account through the normal OAuth flow if needed; this setup does not
enable Settings Sync, purchase a Copilot plan or change any assistant provider.
For native release artifacts, explicitly use cargo build --locked --release.
For release WASM, run the usual wasm-pack command with --release. Do not
claim the development smoke as release, deployment or real-corpus proof.
Use a 30-minute idle timeout and a 30-day retention period for the initial
machine. Closing a browser tab or desktop connection does not stop compute.
Stop your owned machine from the Codespaces list when idle; do not stop a
peer's machine. Reconnect the same machine to preserve /workspaces.
Review the machine's auto-delete date and update retention if needed.
Idle stop is best effort; terminal activity can keep a machine running.
/workspaces survives a container rebuild; container-home tooling and browser
caches may need reinstalling. Cargo output is in target/; the virtualenv,
viewer/pkg, viewer/dist and pnpm modules are regenerable, ignored outputs.
Never delete caches during an active build. A distinct worktree has its own
output directories; budget their storage. Do not bind all worktrees to one
shared Cargo target directory while different agents build concurrently.
Concurrent clients use separate branches/worktrees and one landing owner:
git worktree add /workspaces/rvt-codex -b codex/MY_TASK
git worktree add /workspaces/rvt-claude -b claude/MY_TASKRun the shared bootstrap in a new worktree when its artifacts are needed.
Before deletion or expiry, push every owned branch and export unique evidence
to durable storage. /workspaces is persistent for that machine, not a
backup after Codespace deletion. No automatic cleanup of unpushed source,
credentials, peer work or unique evidence is configured.