Publishing Packages

Build, publish, and consume agentOS packages — locally, from npm, or from your own repo.

agentOS packages — WASM command sets and packed JS agents alike — go through one lifecycle, owned by the @rivet-dev/agentos-toolchain CLI. This page covers the full flow: building a package, publishing it to npm, and wiring a consumer at either a published version or a local checkout.

The lifecycle

Every package is an npm package whose default export points at a self-contained runtime dir (dist/package/) that the sidecar projects under /opt/agentos/<name>/<version>. The toolchain provides four subcommands:

Command	What it does
`stage --commands-dir <dir>`	Populate `bin/` from a directory of compiled binaries, per the `commands` / `aliases` / `stubs` lists in the package’s `agentos-package.json`.
`build`	Assemble `dist/package/` from `bin/` (+ optional `share/`): a clean `package.json` with a `bin` command map, plus the runtime `agentos-package.json`.
`pack`	Build a self-contained node-closure package from an npm package or local dir (JS agents; validates headers, rejects native addons).
`publish`	Publish the built package to npm. Dist-tag is `dev` by default; the `latest` pointer only moves with an explicit `--latest`.

Building

In the secure-exec registry, the just recipes drive the toolchain (see Building Binaries):

just registry-native            # compile the native wasm binaries (once per checkout)
just registry-build             # stage + assemble every registry package
just registry-build coreutils   # ... or one package
just registry-status            # inspect: version, staged bin/, assembled dist

Publishing

Registry packages version independently — each package carries its own semver in its package.json. Bump and commit the version, then:

just registry-publish coreutils            # publish under dist-tag `dev`
just registry-publish coreutils my-branch  # ... under a custom tag
just registry-publish coreutils latest     # DELIBERATE release: moves `latest`
just registry-publish-all                  # every built software package, tag `dev`

Consumers installing @agentos-software/<name> with no tag resolve latest, so latest is reserved for deliberate releases — a dev publish can never clobber what users install.

Consuming published packages

In agent-os, the @agentos-software/* packages are pinned per-package in the workspace catalog. Manage the pins with the just recipes (never hand-edit them):

just agentos-pkgs-status                    # current mode + pinned versions
just agentos-pkgs-set-version coreutils 0.3.1   # pin one package
just agentos-pkgs-update                    # re-pin all from the `latest` dist-tag
just agentos-pkgs-update dev                # ... or from another tag

Local development

Both sides consume local builds by default:

secure-exec: the registry packages are pnpm workspace members, so its tests and examples always resolve the in-repo builds — publish nothing while iterating.
agent-os: the committed dependency state is file-based — link:/path deps into the sibling ../secure-exec checkout, with a committed .github/refs/secure-exec sha that CI materializes the sibling at. Keep a sibling checkout, build its registry packages (just registry-native + just registry-build there), and everything resolves locally with no mode flipping. Advance the dependency with just secure-exec-bump [sha].

Published-version pins exist only transiently inside agent-os publish workflows (release-swap): previews auto-cut a secure-exec preview at the committed ref, releases pin a real secure-exec release — and the swap is never committed.

Publishing from your own repo

The toolchain is not registry-specific — any repo can produce and publish agentOS packages with npx @rivet-dev/agentos-toolchain:

# a package dir with package.json + agentos-package.json + your compiled binaries
npx @rivet-dev/agentos-toolchain stage --commands-dir ./build/wasm
npx @rivet-dev/agentos-toolchain build
npx @rivet-dev/agentos-toolchain publish --tag dev      # or --latest for a release

For a JS agent, pack replaces stage/build:

npx @rivet-dev/agentos-toolchain pack . --out dist/package --agent my-acp-entrypoint

The published package is a plain npm dependency — consumers import its descriptor and pass it to software exactly like the registry packages. See Software Definition for the descriptor shape.