Building Binaries

Compile WASM command binaries for agentOS from source in the secure-exec registry.

WASM command packages ship compiled .wasm binaries in their bin/ that run inside the VM as guest commands. The binaries are build artifacts and are not checked into git, so to add or change a command you build it from source in the secure-exec registry.

Where it lives

Command source and packages live under registry/ in secure-exec:

• registry/native/crates/commands/<name>/: the Rust source for each command — a cargo package named cmd-<name> that emits a <name> binary.
• registry/native/c/: the C source for the C-built commands.
• registry/software/<name>/: the npm package for each command set (@agentos-software/<name>). It exports a { packageDir } descriptor pointing at the self-contained runtime directory assembled at dist/package/, and declares which binaries it ships in its agentos-package.json (commands, plus optional aliases and stubs).

Build

Everything runs through just recipes at the secure-exec repo root:

just registry-native           # compile ALL native wasm binaries (slow; once per checkout)
just registry-native-cmd sh    # recompile ONE command (cargo package cmd-sh)
just registry-build            # stage + assemble every registry package
just registry-build ripgrep    # ... or just one
just registry-status           # per-package state; --remote adds npm dist-tags

The native build compiles each command for wasm32-wasip1 with the pinned nightly toolchain from rust-toolchain.toml (the build vendors and patches std for WASI), optimizes with wasm-opt, and drops the binaries in registry/native/target/wasm32-wasip1/release/commands/. C-based commands (e.g. sqlite3, unzip, wget, zip) compile with a wasi-sdk clang toolchain via make -C registry/native/c.

Each package’s build then runs the agentos-toolchain lifecycle: agentos-toolchain stage copies the binaries listed in the package’s agentos-package.json into its bin/, and agentos-toolchain build assembles the clean dist/package/ runtime dir (the { packageDir } target) with a bin map in its package.json.

Add a new command package

1. Add the command source as registry/native/crates/commands/<name>/ (cargo package cmd-<name>; Rust) or under registry/native/c/ (C).
2. Create registry/software/<name>/ as an @agentos-software/<name> npm package that exports a { packageDir } descriptor pointing at dist/package/.
3. Declare the shipped binaries in its agentos-package.json: { "commands": ["<name>"] } (plus aliases/stubs if needed).
4. If it belongs in a meta-package (e.g. common or build-essential), add it there.
5. Verify with just registry-native-cmd <name> && just registry-build <name> and just registry-test.

Let an agent build it

This is a mechanical, well-scoped task, so you can hand it to a coding agent. A prompt like:

Add a WASM command package for `<command>` to the secure-exec registry:
- put the Rust source at registry/native/crates/commands/<command>/ as a cargo
  package named cmd-<command>,
- create registry/software/<command>/ as an @agentos-software/<command> npm
  package that exports a { packageDir } descriptor and declares the command in
  its agentos-package.json,
then run `just registry-native-cmd <command> && just registry-build <command>`
and `just registry-test`, and fix any failures.

Using the registry

Install a published package and pass it to software. Registry WASM packages are { packageDir } descriptors — import and pass them directly:

import { agentOS, setup } from "@rivet-dev/agentos";
import coreutils from "@agentos-software/coreutils";
import ripgrep from "@agentos-software/ripgrep";

const vm = agentOS({ software: [coreutils, ripgrep] });

export const registry = setup({ use: { vm } });
registry.start();

Meta-packages bundle a full set, e.g. @agentos-software/common (coreutils, sed, grep, gawk, findutils, diffutils, tar, gzip). Run the commands from the client; see Processes & Shell. Browse the full catalog on the Registry, and see the package descriptor in Software Definition. To ship your package to npm or use a local build, see Publishing Packages.