orbx: Instructions file for Codex

AGENTS.md

This file — also read as CLAUDE.md (a symlink to it) — provides guidance to coding agents (Claude Code, GitHub Copilot CLI, and others) when working with code in this repository.

What this is

orbx (Orbstack linuX) is a single-file, zero-dependency Bash CLI that spins up per-project OrbStack Linux machines. It derives a machine name from $PWD, mounts the project into the VM, provisions it from a cloud-init template, waits for readiness, and shells in. All product code lives in one script: bin/orbx.

Commands

bats test/                              # run all tests
bats test/shellrun.bats                 # run one file
bats -f "run forwards flags" test/      # run tests matching a name

shellcheck bin/orbx test/helpers/orb-stub script/release   # lint (CI pins v0.11.0)

script/release X.Y.Z                    # cut a release (see below)

There is no build step — bin/orbx is the shipped artifact.

Architecture

Dual-mode script. bin/orbx runs as an executable or is sourced. The guard at the bottom (if [[ "${BASH_SOURCE[0]}" == "${0}" ]]) means main runs only when executed; when sourced, only the orbx::* functions load. Tests rely on this: orbx_source (unit-test individual functions) vs orbx_run (integration through main). set -euo pipefail is set inside that guard, so it does not apply when sourced.

Config layering. Precedence, most-specific wins: CLI flags > ./.orbxrc > ~/.orbx/config > built-in defaults. orbx::effective_config merges the two flat key = value files over defaults; orbx::resolve_context then re-reads that plus the parsed ORBX_FLAG_* vars and populates the ORBX_* run-state globals every command reads. Config is parsed line-by-line (orbx::parse_config_file) and never sourced or eval'd — a config file can't execute code. Keep it that way. Values can't contain # (everything after # is a comment).

Template resolution. Templates are cloud-init YAML. A bare name is resolved through a search path (orbx::resolve_template): $ORBX_TEMPLATE_DIR → ~/.orbx/templates → bundled dir → <script>/../templates. A user file shadows the bundled one of the same name. A path-shaped value — one with an explicit ./, ../, / or ~/ prefix, or a .yaml/.yml extension — skips the search path entirely and is used as given, resolved against $PWD (the same anchor as ./.orbxrc). That is what lets a repo commit its own template alongside its config; the two forms are disjoint, so a bare name never changes meaning. ORBX_BUNDLED_TEMPLATE_DIR is the literal @TEMPLATE_DIR@ placeholder in-repo; the Homebrew formula rewrites it at install time (unstamped in a git checkout, which is why the <script>/../templates fallback exists).