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
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:
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 (default64MiB; accepts bytes,KiB,MiB, orGiB, and must be greater than zero).AMUX_LOG_BACKUP_COUNT: retained rotated generations (default2, range0..16).AMUX_LOG: tracing filter for daemon/shim diagnostics. It takes precedence overRUST_LOGand defaults toamux=info.- State directories are mode
0700; sockets and state files are mode0600.
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
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:
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
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.