native-runners.json
Named profiles declare a stable runner ID, startup directory, discovery choice, explicit served directories, and optional remote terminal access.
amux · native runner configuration
One runner.
Every directory.
Native Amp now serves many directories and owns its update behavior. amux keeps the small missing layer: a declarative profile
for code roots, Obsidian vaults, and other directories, plus a systemd or launchd service that starts Amp at login.
A small declarative layer.
Configure the directories once, install the native service, and let Amp own execution and updates. Click a term to see the exact boundary.
Touches
Clear ownership, less machinery.
Amux remains active, but only where it adds value. Native Amp owns runners and coordination; the operating system owns process supervision.
mixed roots
Discover Git repositories beneath a code root while explicitly serving unrelated paths such as an Obsidian vault or dotfiles.
one runner by default
Prefer one profile per machine. Add another only when a separate native identity or isolation boundary is genuinely required.
systemd · launchd
Amux generates and activates one owned service artifact per profile. The operating system starts and keeps the native Amp process alive.
Amp runs directly
Generated services execute the resolved amp binary. Amux is not resident and does not proxy or supervise runner traffic.
safe ownership
Installed artifacts are recorded by digest. Amux refuses to overwrite or remove a service file it cannot prove it created.
doctor · JSON · dry-run
Preview installation, verify configuration and service state, and consume versioned result envelopes in automation.
native updates
Amp owns update and idle-restart behavior, subject to its installation and settings. New profiles do not need Amux’s legacy scheduled maintenance.
dynamic additions
amp runner dirs add|list|remove remains available for temporary local choices alongside declarative machine-critical paths.
Deprecated, then removed.
Amux itself is active. Its former coordination model is not: the old commands below have been removed, and current Amux does not create, adopt, migrate, drain, rewrite, or delete their historical state.
workers · spawn · adoption
Removed. Create native Amp threads on the exact intended Orb or live runner/workdir.
groups · reports · callbacks
Removed. Use native parent/reply routing, authenticated messages, waiting, and native dependency relationships.
shelves · deadlines
Removed. Use native Amp archive state and native coordination rather than Amux lifecycle records.
worker teardown · finish
Removed. Manage native thread completion and archive separately. Current runner teardown is local runner/worktree cleanup only.
historical stores
Worker, shelf, group, report, callback, operation, and spawn-assignment files are inert evidence. Leave them untouched.
/amux-tycho
The explicit-only Tycho receipt bridge is separate from the removed worker-report route and is never selected implicitly.
Configure the machine, then use Amp.
The bundled /amux skill configures native runner profiles and their login services. It routes delegated work through
native Amp. Legacy per-workdir recovery remains available during migration, not as the default architecture.
$ npx skills add zainfathoni/amux --skill amux --global
See the skill guide and trigger reference.
“Serve my code and vault”
configure one native-runners.json profile“Start it at login”
amux runner service install“Check the runner service”
amux runner service doctor“Remove the login service”
amux --dry-run runner service remove“Recover a legacy runner”
use the scoped per-workdir lifecycle“Teardown this worktree”
two-step runner teardown plan + fresh digest“Delegate work”
authenticated native Amp creation on the exact executor/workdir“/amux health”
skill-only · read-only responsiveness check“/amux sprawl”
skill-only · coordinated native child threadsA binary and
the Amp CLI.
The checksum-verifying installer supports Linux and macOS arm64/amd64 and installs to ~/.local/bin/amux.
Homebrew and other package-manager installs must remain owned and updated by that manager.
See the README for pinned releases, Homebrew, source builds, and update ownership.
$ curl -fsSL https://amux.zainf.dev/install.sh | sh
$ amux version
$ amux install doctor
$ amux --dry-run runner service install
# Homebrew owns Homebrew installs
$ brew install zainfathoni/tap/amux
$ brew upgrade amux