Ship a distribution

Build a distribution ends with a command you run from source. This walkthrough takes it the rest of the way: a compiled, self-updating acmedev binary you hand to your team. Use it when your organization needs a private agent adapter, policy plugin, content catalog, or telemetry sink in one reviewed executable.

The canonical implementation is examples/acme-distribution. The repository typechecks it on every pull request and compiles and smoke-tests it during package verification. Follow the linked source files instead of copying a second implementation from this page.

What the example contains

Internal adapter

Detects acme-agent, declares its instruction, MCP, and skill files, parses them without I/O, and provides a safe MCP writer.

Private content

Bundles an instruction snippet, two Agent Skills, an MCP catalog definition, and a platform preset through absolute content URLs.

Distribution boundary

Composes official and private plugins, branding, a default preset, and an optional telemetry sink at build time.

Compiled verification

Derives every content entrypoint, compiles with Bun, then exercises the binary on a deterministic seeded machine.

Self-updating binary

A second entry point declares a private release source and a standalone installation, so the compiled executable replaces itself while the package entry point cannot.

Follow the implementation

1. Start from the package manifest. A real distribution pins the public CLI, SDK, and testkit packages to the same exact release.

2. Read the internal adapter. Its lifecycle is the important boundary:

   • detect may use the injected environment.
   • files declares absolute paths for core to read.
   • parse is synchronous and receives only captured data.
   • mcpWrite preserves unrelated entries or refuses unsafe shapes.

3. Read the private plugin. It registers the adapter, a distribution check, bundled content, a lazy skill driver, a source denylist, and the default preset.

4. Inspect the platform preset. It selects policy and onboarding defaults. The MCP server appears in the normal setup picker; use acmedev setup --add mcp to reopen that step after the first setup.

5. Read the composition boundary and the two entry points that use it — main.boundary.ts for a package-manager run and standalone-main.boundary.ts for the compiled binary. These are the only modules that read ambient process state, and they compose rather than discover the plugin list.

6. Read the build script and content entrypoints. Bun compiles the standalone entry point, and every Markdown and JSON asset must be passed to it; omitted assets otherwise disappear without a build error.

7. Run the source checks, then the clean-room package verification from an Aura checkout.

   pnpm --filter acme-distribution-example typecheck
   pnpm verify:packages

What just happened?

The distribution fixed its trusted code and content at build time. The preset remained data-only, the adapter separated I/O from parsing, and every eventual filesystem change still flows through Aura’s preview, lock, backup, rollback, and undo kernel.

Skills and MCP definitions contain references rather than secrets. Private registry credentials belong only in distribution CI, and a compiled binary cannot keep an embedded bearer token secret.

Optional telemetry boundary

A distribution sends nothing unless it composes a telemetry sink. The example sink buffers privacy-safe events and flushes once under a short timeout. DO_NOT_TRACK or AURA_TELEMETRY=off disables the sink before it sees an event.

Treat a compiled endpoint credential as public. Use a write-only ingestion endpoint with server-side validation and abuse controls, or acquire a narrowly scoped user credential at runtime.

Let the executable update itself

The example keeps package-manager and standalone entry points separate. Only the compiled entry calls runStandaloneCli with a private release source, so it can replace its own executable while an npx, npm-global, or source run cannot reach installation code.

Add distribution updatesConfigure GitHub or signed-manifest releases, package trusted archives, rotate keys, and diagnose skipped updates.

Common failures

Symptom	Cause	Fix
Internal agent is not detected	Its semver-producing executable is absent from PATH	Add a test shim or install the executable, then rerun the source check.
Content is unavailable	A contribution URL is relative, missing, or points outside staged assets	Use pluginContentUrl and verify every asset in the compiled binary.
MCP cannot converge	The adapter has no matching safe writer or the current file is malformed	Implement read/write symmetry and refuse unrepresentable configuration.
Binary passes --help but loses a skill file	The build entrypoint list omitted a nested asset	Derive, sort, compile, and smoke-test every content entrypoint.

Next steps

Plugin referenceReview contribution identities, content URLs, and trusted-code boundaries.

Testkit READMESeed machines and exercise source or compiled distributions deterministically.