ompact packages a Linux build of oh-my-pi (omp) as a host-native
smolvm single-file executable. It boots the embedded VM and runs
/usr/local/bin/omp by default.
| Phase | Requirements |
|---|---|
| Build | Linux x86_64/arm64 or macOS arm64, network access, a preinstalled smolvm CLI, and mkfs.ext4 on PATH. |
| Linux virtualization | KVM access through a readable and writable /dev/kvm. |
| macOS graphics | Homebrew libepoxy and virglrenderer runtime libraries. Install e2fsprogs, startergo/virglrenderer/virglrenderer, and its tap dependencies (startergo/angle, startergo/gn, and startergo/libepoxy). Add e2fsprogs' sbin directory to PATH. |
| Runtime | A host supported by smolvm with matching architecture; the artifact is host-native, not a portable application. |
make buildThe build creates a disposable builder VM, runs the selected environment
scripts and Smolfile bootstrap, verifies the guest inputs, and writes
ompact in the repository root. make check runs the repository checks;
make smoke builds the artifact and runs its runtime test.
Smolfile is the source of truth for the guest and packaged artifact:
| Setting | Purpose |
|---|---|
env |
Shared guest environment defaults. |
init |
Ordered bootstrap commands for packages, tools, and the omp launcher. |
image |
Debian base image pin. |
cpus, memory |
Default builder and packaged VM resources. |
net |
Default networking; disabled for packaged runtime by default. |
[artifact] |
Packaged VM resources, entrypoint, and command marker. |
Mutable versions, checksums, and installer details live in Smolfile and
the selected env/*.sh scripts. The base bootstrap includes omp, jj,
fd, rg, sd, ast-grep, and gh; environment scripts own additional
tools and caches.
Update an input in its owning file, then run make check.
The optional first build.sh argument selects comma-separated names of
executable scripts under env/. Set Make's ENVIRONMENTS variable to pass
the same list. Omit the list for a base-only build.
make build ENVIRONMENTS=rust,go| Script command | Responsibility |
|---|---|
defaults |
Print build-time KEY=VALUE defaults. |
install-system |
Install system-owned components as root. |
install-user |
Install user-owned tools as omp. |
check |
Verify the environment as omp and run a minimal probe. |
Create an executable env/<name>.sh implementing the commands above;
unused install phases should be successful no-ops.
defaults may include repeated ENV_PATH=/absolute/path entries. These
directories are prepended to the builder and packaged runtime PATH in
selection order.
Other entries become builder environment variables.
| Variable | Effect |
|---|---|
OUTPUT |
Output path; defaults to ompact in the repository root. |
CPUS |
Overrides builder and packaged VM vCPU defaults. |
MEMORY |
Overrides builder and packaged VM memory defaults. |
ENVIRONMENTS |
Makefile-only comma-separated environment list. |
Environment-specific overrides and constraints are defined by their owning
env/<name>.sh scripts.
CPUS=8 MEMORY=16384 OUTPUT=/path/to/ompact ./build.sh rust,goEach build starts from scratch, removes its disposable builder, and replaces only its owned regular output file. Existing directories, sidecars, and unexpected output files cause the build to abort.
On failure, the build reports the failed command and exit status; environment setup failures also identify the failed step.
Runtime networking is disabled by default. The packaged runtime starts in
/workspace by default, so mount the project there and provide a writable
OMP state directory; add --net only when the workload needs network access:
mkdir -p "$HOME/.omp"
./ompact run -it --net \
-v "$PWD:/workspace" \
-v "$HOME/.omp:/home/omp/.omp" \
-- /usr/local/bin/ompThe packaged VM sets the omp user's global Git config to trust
/workspace, allowing Git to operate on host-mounted repositories without
using a repository-local config.
The image installs GitHub's currently published SSH host keys from
https://api.github.com/meta into /etc/ssh/ssh_known_hosts for system-wide
host verification.
When Git or SSH needs host authentication, add --ssh-agent to the run
command. The host must expose its agent through SSH_AUTH_SOCK; smolvm
forwards signing requests without copying private keys into the VM.
Model credentials are launch-time inputs supplied with -e or smolvm's
secret mechanism.
The active agent directory can be checked with the same state mount:
./ompact run \
-v "$HOME/.omp:/home/omp/.omp" \
-- /usr/local/bin/omp --no-session config pathomp config path is authoritative when a profile or
PI_CODING_AGENT_DIR changes the location. Mount the directory, not an
individual config file, and keep it writable. Mount only dependency caches
declared by selected environment scripts; project dependencies still need
network access unless cached.
| Concern | Behavior |
|---|---|
| SSH credentials | --ssh-agent forwards the host agent's signing interface; private keys remain on the host. |
| Runtime identity | The wrapper runs workloads as the non-root omp user. Explicit guest commands that bypass the wrapper are outside this guarantee. |
| State mounts | $HOME/.omp exposes authentication, sessions, and runtime state. Use a dedicated writable directory owned by a non-root host user; root-owned 0700 sources are rejected. |
| Network | build.sh enables networking only for the temporary builder. Runtime callers opt in with --net; this is not an external no-network guarantee. |
| Credentials | Credentials and secrets are supplied at launch and are not stored in the host executable, image, or build script. |
The build uses smolvm pack create --single-file and produces one executable
without a .smolmachine sidecar. Redistribute and replace that executable
as a whole. The format does not make the package host-independent or persist
runtime state; macOS may also require additional notarization work.
The artifact bundles third-party software (Debian packages, omp, jj,
fd, rg, gh, sd, ast-grep, uv, and toolchain components) governed
by their own upstream licenses; this repository's MIT license covers only
the packaging code in this repository.