Skip to content
fgschPublic

About

Package oh-my-pi as a portable smolvm executable

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

97 Commits

Folders and files

Repository files navigation

ompact

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.

Requirements

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.

Build

make build

The 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.

Configuration

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.

Environments

Selecting environments

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

Adding an environment

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.

Build overrides

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,go

Each 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.

Run

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/omp

The 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 path

omp 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.

Security

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.

Packaging

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.

About

Package oh-my-pi as a portable smolvm executable

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages