amux-runtime 0.1.0

Persistent process and TTY runtime for AI agents, with durable logs and human attach
Documentation

amux

English | 简体中文

amux is a persistent process and TTY runtime for AI agents, with durable logs and human attach. It is implemented entirely in Rust.

A workspace is a durable logical context backed by a named daemon. Processes in the same physical workspace share a group shim while retaining independent supervisors, PTYs, logs, and process groups:

amux CLI -> named daemon -> one group shim per workspace -> OS process groups

Build and quick start

cargo build --release
export PATH="$PWD/target/release:$PATH"

amux workspace create dev
amux run --workspace dev --name api -- sh -c 'while true; do date; sleep 1; done'
amux run --workspace dev --name shell --tty -- /bin/sh
amux ps --workspace dev --json
amux attach dev/shell

The CLI lazily starts the selected daemon when its Unix socket is absent. During attach, Ctrl-P Ctrl-Q detaches without terminating the process. Pipe output is read with amux logs; it is never exposed as a fake terminal.

Inside an amux-managed process, AMUX_WORKSPACE supplies the default for amux run --workspace and amux shell --workspace. This lets an enclosing workspace manager select an isolated runtime without wrapping the amux CLI. AMUX_PROCESS_ID is also inherited: nested amux run and amux shell requests automatically record their parent process.

Managed processes receive trusted AMUX, AMUX_WORKSPACE, AMUX_WORKSPACE_ID, AMUX_PROCESS, AMUX_PROCESS_ID, and AMUX_IO_MODE variables. Nested attach from a managed process is rejected.

Useful commands:

amux daemon list
amux daemon start work
amux daemon status work
amux --daemon work ps
amux daemon stop work
amux daemon rm work
amux workspace ls
amux ps --workspace dev
amux inspect dev/api
amux logs --after 10 --jsonl dev/api
amux logs --follow dev/api
amux attach --readonly dev/shell
amux attach --takeover dev/shell
amux signal dev/shell INT
amux stop dev/api
amux kill dev/api
amux wait dev/api --json
amux restart dev/api
amux rm dev/api
amux workspace rm dev

Configuration:

  • AMUX_DAEMON: selected daemon name (default: default).
  • AMUX_STATE_DIR: persistent metadata and output logs.
  • AMUX_SOCKET: test/debug-only direct Unix socket override.
  • AMUX_LOG_ROTATE_SIZE: active logical log size before rotation (default 64MiB; accepts bytes, KiB, MiB, or GiB, and must be greater than zero).
  • AMUX_LOG_BACKUP_COUNT: retained rotated generations (default 2, range 0..16).
  • AMUX_LOG: tracing filter for daemon/shim diagnostics. It takes precedence over RUST_LOG and defaults to amux=info.
  • State directories are mode 0700; sockets and state files are mode 0600.

amux daemon rm <name> permanently deletes all persistent state for a named daemon. It is accepted only after that daemon has stopped, is idempotent when the state is already absent, and does not lazily start or connect to a daemon.

Process output is stored as one active output/current/ generation plus UTC timestamped output/<timestamp>.bak/ generations. Every generation contains its raw stream files and matching events.jsonl, so event offsets always refer to files in the same directory. amux logs reads retained generations oldest first. When --after points into discarded history, JSONL output includes a gap record and plain output reports the gap on stderr before continuing with the oldest retained output. amuxd.log and workspace shim.log use the same size and backup-count policy with <name>.<timestamp>.bak backups.

Daemon and shim diagnostics use compact tracing output. They include stable daemon, workspace, group, process, and execution identifiers, but never managed process output, environment variables, request bodies, or terminal bytes. Ordinary CLI tables/JSON and managed process OutputEvent streams remain separate public output planes. Panic information is routed through the same diagnostic pipeline after startup.

The distributable Codex Skill lives at skills/amux. Install or link that directory as amux in the active Codex skills home. Treefold-managed Sessions can use the same Skill directly because Treefold injects AMUX_DAEMON, AMUX_WORKSPACE, and AMUX_PROCESS_ID.

Development

just test
just lint
just build

Treefold consumes amux-runtime, the amux CLI, and skills/amux from one resolved checkout. For development across arbitrary worktree paths, see Treefold integration.

Linux and macOS are supported. The first runtime driver is host. Persistence covers Treefold/CLI reconnects. Stopping or losing a daemon deliberately stops all of its group shims and business process groups.

License

Copyright (c) 2026 win5do and amux contributors.

Licensed under either of:

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.