# Awman > Guide for using awman to run AI coding agents in isolated containers with multi-step workflows and a REST API. Use when configuring parallel agent sessions, authoring awman workflows, driving the awman api server, managing worktrees, migrating from amux, or troubleshooting awman container runs. - Skill: `vinnie357/awman` (Agent Skill, multi-file: 11 files) - Install (CLI): `npx skillmds add vinnie357/awman` - Raw SKILL.md: https://api.skillmd.com/api/skills/vinnie357/awman/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: Apache-2.0 - Author: vinnie357 (https://skillmd.com/u/vinnie357) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/vinnie357/awman --- # awman awman is a Rust CLI and TUI for running AI coding agents (Claude Code, Codex, OpenCode, and others) in isolated Docker or Apple Containers sandboxes. It coordinates parallel agent sessions, executes multi-step workflows, and exposes a REST API for headless programmatic control. **awman is not a tmux wrapper.** The name invites that assumption. awman ships its own tab-based TUI with its own keybindings. Tmux is not a dependency. awman was previously named **amux**. See "Migrating from amux" below. Source: https://github.com/prettysmartdev/awman (accessed 2026-07-13) License: Apache-2.0 | Latest at research time: v0.11.0 (2026-07-13) ## Prerequisites A container runtime, set via the global-only `runtime` config key (`awman config set --global runtime `, then `awman ready`): | `runtime` value | Platforms | Requirements | |-----------------|-----------|--------------| | `docker` (default) | Linux, macOS, Windows | Docker daemon | | `apple-containers` | macOS 26+ | native `container` CLI | | `docker-sbx-experimental` | macOS arm64, Windows x86_64 | `sbx` CLI (`brew install docker/tap/sbx` + `sbx login`) | `docker-sbx-experimental` (new in 0.10.0) runs each session in a dedicated microVM — private kernel, filesystem, and Docker daemon. It does **not** honor `dir()`, skill, or context overlays; networking goes through an HTTP/HTTPS proxy (raw TCP/UDP blocked); sandboxes persist between sessions. The runtime must be running and healthy before any `awman` session starts. This runtime requires a free Docker account; `sbx login` is a one-time authentication step that must complete before `awman ready` reports the runtime healthy. ## Install Mise is the recommended install path. It manages the version, pins reproducibly, and uses the GitHub releases backend — no extra dependencies. A ready-to-copy pin lives at `templates/0.11.0/mise.toml` in this skill — copy it into the target repo's `mise.toml` (or merge under `[tools]`) and run `mise install`. **Global pin (one-time, any project):** ```sh mise use -g github:prettysmartdev/awman@0.11.0 ``` **Per-project pin (recommended for repos that run awman):** ```sh cp templates/0.11.0/mise.toml /mise.toml # then: cd && mise install ``` The template's contents: ```toml [tools] "github:prettysmartdev/awman" = "0.11.0" ``` **Verify:** ```sh mise which awman && awman --version ``` Fall back to the upstream installer (`curl -s https://prettysmart.dev/install/awman.sh | sh`) only when mise is unavailable (locked-down CI image, no GitHub release network access). State the reason explicitly when doing so. Building from source requires Rust 1.94+ and `make` (`git clone https://github.com/prettysmartdev/awman.git && cd awman && make install`). Do not use Homebrew, asdf, or mason — none are documented by upstream. ## Migrating from amux The rename is automatic for existing users: - Config migrates automatically on first run. Change any `AMUX_*` environment variables to `AWMAN_*` and you are done. - The binary is now `awman`; the installer offers to clean up old `amux` binaries. - Config keys under `headless.*` are now under `api.*` (e.g. `headless.workDirs` → `api.workDirs`). - The server command `amux headless start` is now `awman api start`. - Per-repo config moved from `aspec/.amux.json` to `GITROOT/.awman/config.json` (see Config below). - Markdown workflow files (`.md`) are **no longer supported** — use TOML or YAML. ## First-Run Diagnostic awman is pre-1.0 and ships frequently. Run these before trusting that docs match the installed binary: ```sh awman --version awman config show ``` `awman config show` prints the merged effective config (global + per-repo). Use it to verify `runtime`, `default_agent`, and overlay state rather than reading JSON files directly. ## Command Tree | Command | Purpose | |---------|---------| | `awman init [--aspec] [--agent ]` | Scaffold project: writes `.awman/config.json` and per-agent Dockerfiles | | `awman ready [--refresh]` | Verify environment; `--refresh` re-audits and rebuilds the agent Dockerfile | | `awman chat [--agent ] [--auto] [--yolo]` | Interactive agent session in a TUI tab | | `awman exec prompt "" [--issue ]` | One-off prompt without a persistent session | | `awman exec workflow [--work-item \| --issue ] [--yolo] [--worktree] [--max-concurrent ]` | Run a multi-step workflow file | | `awman exec workflow --dynamic --work-item [--leader ]` | Leader agent designs and runs a workflow (0.11.0) | | `awman clean [--dry-run] [--yes]` | Remove stopped containers, dangling images, completed-workflow data (0.11.0) | | `awman new spec\|workflow\|skill [--interview] [--issue ]` | Scaffold a work item, workflow, or custom skill | | `awman specs amend ` | Update an existing work item | | `awman status [--watch]` | Session/workflow dashboard | | `awman config show\|get\|set [--global]` | Inspect/modify merged config | | `awman api start\|status\|logs\|kill` | Manage the REST API server (default port 9876) | | `awman remote run\|session` | Drive a remote awman api server | | `awman` (no args) | Open the TUI | See `templates/0.11.0/commands.md` for the full v0.11.0 command surface with flags and examples. ## GitHub Issue Integration (0.10.0) `--issue ` on `new spec`, `exec workflow`, and `exec prompt` fetches a GitHub issue and injects it. Reference forms: bare number (`--issue 84`, requires a GitHub `origin` remote), shorthand (`--issue owner/repo#84`), or full URL. Auth resolution: `gh` CLI → `GITHUB_TOKEN` → unauthenticated REST (public repos, 60 requests/hour). For `exec workflow` the issue populates the `{{work_item_*}}` template variables exactly as `--work-item` does; `--issue` and `--work-item` are mutually exclusive. ## Dynamic Workflows (0.11.0) `awman exec workflow --dynamic --work-item ` launches a **leader agent** that reads the work item, designs a `workflow.toml`, and executes it — no hand-authored workflow file. `--dynamic` auto-enforces `--yolo`, `--worktree`, and the `context(workflow)` overlay; passing them explicitly is a no-op, and `--dynamic` rejects a workflow path, `--plan`, or a missing `--work-item`. Leader resolution (highest wins): `--leader ` flag → `dynamicWorkflows.defaultLeader` config → `--model` on the project default agent → project default agent and model. The `dynamicWorkflows` config section constrains the plan: `agentsToModels` (approved agent→model map; empty falls back to Dockerfile discovery), `maxConcurrentSteps` (advisory, not runtime-enforced), and `guidance` (project instructions injected into the leader prompt, max 50 × 1,000 chars). An invalid generated workflow triggers a repair agent up to 3 times. See `references/config.md` for the key schema. ## Parallel Execution (0.11.0) Workflow steps with identical `depends_on` sets form a parallel group and run **concurrently**. Cap simultaneous containers with `maxConcurrentAgents`; precedence: `--max-concurrent` flag → `AWMAN_MAX_CONCURRENT_AGENTS` env → repo config → global config → **unlimited**. `1` disables parallelism; `0` is rejected. A failed step without `abort_on_failure` lets siblings continue; `abort_on_failure = true` kills all active peers. Stuck detection (30 s) and yolo countdowns (60 s) track per container. See `references/config.md` for the `maxConcurrentAgents` key schema and `references/workflows.md` for full parallel-group grammar and worked examples. TUI: `Ctrl-S` rotates focus between parallel containers; `Ctrl-G` toggles a git sidebar (per-file `+/-` counts, ~2 s refresh, compact `+X -Y` in the status bar when closed); `Ctrl-,` opens the config dialog (`Ctrl+N` adds nested `dynamicWorkflows` entries). ## Cleanup and Failure Logs (0.11.0) `awman clean [--dry-run] [--yes]` removes stopped containers, dangling awman-labeled images, and completed-workflow data (repo `.awman/workflows/` state, `~/.awman/context/workflows/` dirs). In-progress workflows and active containers are preserved. Failed step output (~100 lines) lands in `~/.awman/logs/{workflow-id}-{step-name}-{container-name}.log` — created on demand, **never auto-cleaned** (not even by `awman clean`). Teardown `on_failure` remediation agents receive the failed command's output as a readable file; setup `on_failure` agents do not. See `references/workflows.md`. ## Agents Supported agents: `claude`, `codex`, `opencode`, `maki`, `antigravity`, `copilot`, `crush`, `cline`. > **`gemini` is deprecated** by Google upstream. Migrate to `antigravity` (`awman chat --agent antigravity` or `awman config set agent antigravity`). The `gemini` agent name remains accepted but logs a deprecation warning and has degraded system-prompt-injection support. Each agent has a Dockerfile in `.awman/Dockerfile.` (seeded from upstream templates). Customize the Dockerfile to add tools or environment configuration for that agent. The project base image path is configurable via the per-repo `dockerfile` config key (default `Dockerfile.dev`) as of 0.10.0. **Selection precedence** (highest wins): 1. Per-step `agent:` field in the workflow file 2. `--agent ` flag on the CLI invocation 3. `agent` key in per-repo `.awman/config.json` 4. `default_agent` key in `~/.awman/config.json` (global default; factory default: `"claude"`) ## Worktrees Opt-in via `--worktree` on `awman chat` / `awman exec`. All steps in a single workflow run share one worktree. Worktrees are **never auto-deleted**. At session end, awman prompts: merge / discard / keep. On abort, the worktree is preserved for manual inspection. Monitor disk use when running repeated `--yolo --worktree` workflow runs. Containers run `--rm` and auto-remove at session end. Only the Git repository is bind-mounted; `/workspace` inside the container is ephemeral beyond what lands in the Git tree. ## Config Files awman reads one `config.json` per scope: | File | Scope | Created by | Commit? | |------|-------|-----------|---------| | `~/.awman/config.json` | Global | Manually or `awman config set --global` | No | | `GITROOT/.awman/config.json` | Per-repo | `awman init` | Yes | Per-repo takes precedence on overlapping scalar keys. The `overlays` string array merges **additively** across all sources (global config, repo config, `AWMAN_OVERLAYS`, `--overlay` flags, workflow steps); other list fields replace. The repo `.awman/` directory also holds per-agent Dockerfiles seeded by `awman init`. XDG base-directory environment variables are honored as of 0.10.0. Always use `awman config show` to see merged values rather than hand-editing the JSON. See `references/config.md` for the full per-key schema (type, default, scope, merge behavior). ## Overlays Overlay specs grant agent containers access to host resources: `dir(HOST:CONTAINER[:ro|rw])`, `ssh()`, `env(VAR)`, `skill(*)`/`skill(NAME)`, and — new in 0.10.0 — `context(global|repo|workflow[:ro])`. Context overlays combine a persistent host directory (`~/.awman/context/...`) with automatic system-prompt injection, giving agents a durable shared workspace across sessions; they default to `rw` so agents accumulate knowledge — pass `:ro` to lock them. On host-path conflicts, `:ro` always overrides `:rw`. See `references/config.md` for the full overlay grammar. ### env passthrough example To make an agent use a local provider or custom endpoint, forward the relevant vars via `env()` overlays: ```json { "overlays": [ "env(ANTHROPIC_BASE_URL)", "env(ANTHROPIC_API_KEY)" ] } ``` Or one-off via CLI flag (repeatable, or comma-separated in a single flag): ```sh awman chat --overlay "env(ANTHROPIC_BASE_URL)" --overlay "env(ANTHROPIC_API_KEY)" # or awman chat --overlay "env(ANTHROPIC_BASE_URL),env(ANTHROPIC_API_KEY)" ``` If `ANTHROPIC_BASE_URL` is not set on the host, awman silently omits it — not an error. > **`envPassthrough` is removed in 0.10.0.** The old `envPassthrough` array config key no longer works; `awman config get envPassthrough` returns a removal notice. Express env forwarding as `env()` overlay entries in the `overlays` array (config file, `AWMAN_OVERLAYS`, or `--overlay` flag) instead. See `references/config.md` for the migration table. ## API Mode `awman api start` runs a REST server on port 9876 (configurable via `--port`). It serves **HTTPS with a self-signed certificate by default** — pass `--dangerously-skip-tls` for plain HTTP in trusted local setups. It accepts bearer-token auth. Sessions are restricted to directories in `api.workDirs` (global config) or passed via `--workdirs`. **FIFO queue per session.** Submitting a second command while one is in flight enqueues it — submission never blocks and returns immediately with a `command_id`. Poll `GET /v1/commands/:id` or stream `/v1/commands/:id/logs/stream` (Server-Sent Events) to track progress. A `POST /v1/sessions` with a workdir outside the allowlist returns HTTP 403. Prefer `awman remote` over raw curl when driving the server from the CLI — it carries auth and the session header per the operator-tooling-first convention. See `references/api.md` for the full endpoint table and curl examples. ## Workflow Authoring Workflows are TOML (`.toml`) or YAML (`.yml`/`.yaml`) files authored via `awman new workflow [--interview]` and executed via `awman exec workflow `. **Markdown (`.md`) workflows are no longer supported as of 0.9.1.** Step fields are lowercase only: `name` and `prompt` are required; `depends_on`, `agent`, `model`, and `overlays` are optional. Template variables available in prompts: `{{work_item_number}}` (zero-padded 4-digit), `{{work_item}}` (bare number), `{{work_item_content}}` (full file or fetched issue), `{{work_item_section:[Name]}}` (named section). New in 0.10.0, workflows support **setup and teardown phases** with typed steps (`clone_repo`, `checkout_create_branch`, `run_shell`, `commit_changes`, `push_branch`, `create_pull_request`, …), including `poll_ci` (block until the branch's GitHub Actions run completes; `interval_secs`/`max_retries`) and per-step `on_failure` blocks that launch a remediation agent and retry the step up to `max_attempts` times. See `references/workflows.md` for grammar in both formats and worked examples. ## Known Sharp Edges (Pre-1.0) - **Not a tmux wrapper.** awman ships its own TUI. The name is misleading. - **Markdown workflows dropped in 0.9.1.** Only TOML and YAML are accepted; other extensions are rejected. - **API server is HTTPS by default.** Local curl needs `--dangerously-skip-tls` (server side) or trusting the self-signed cert. - **Commands queue, not reject.** A busy session enqueues new commands in FIFO order rather than returning 403; a closing session returns HTTP 409. - **`runtime` is global-only.** No per-repo runtime selection. - **`docker-sbx-experimental` skips all overlays.** `dir()`, skills, and context mounts are not honored; networking is proxy-only; sandboxes persist between sessions and lose port mappings on stop. - **`--issue` and `--work-item` are mutually exclusive.** Bare `--issue ` requires a GitHub `origin` remote — use `owner/repo#N` or a URL otherwise. - **Context overlays default to `rw`.** Use `context(SCOPE:ro)` to stop agents from modifying accumulated knowledge. - **`envPassthrough` is removed.** The old config key returns a removal notice. Use `env()` overlay entries in the `overlays` array instead. - **`gemini` is deprecated.** Use `antigravity` as the replacement (`awman config set agent antigravity`). - **`--dynamic` force-enables `--yolo`, `--worktree`, and `context(workflow)`.** There is no supervised dynamic mode. - **Unset `maxConcurrentAgents` means unlimited parallelism.** `1` disables it; `0` is rejected. - **`~/.awman/logs/` grows unbounded.** `awman clean` does not remove failure logs. - **Setup-step `on_failure` gets no automatic output capture.** Only teardown steps hand the failure output to the remediation agent. - **Frequent release cadence.** Re-run `awman --version` when output looks unexpected. Pin in mise to control when you upgrade. - **Lowercase keys only in workflow files.** Uppercase variants are parse errors. ## References - `references/api.md` — REST endpoint table, bearer auth, curl examples - `references/workflows.md` — Workflow grammar in TOML and YAML - `references/config.md` — Per-key config schema for both scopes - `references/command-reference.md` — Full CLI surface with flags and examples - `templates/0.11.0/commands.md` — Immutable v0.11.0 command snapshot - `templates/0.10.0/commands.md` — Immutable v0.10.0 command snapshot (previous version) - `templates/0.9.1/commands.md` — Immutable v0.9.1 command snapshot ## Anti-Fabrication Run `awman --version` and `awman config show` before asserting that any documented behavior matches the installed binary. awman is pre-1.0 and minor bumps carry breaking changes. Every command form in this skill traces to upstream docs sourced from https://github.com/prettysmartdev/awman (accessed 2026-07-13). Mark any behavior not confirmed by that source as "requires verification against awman v0.11.0 source." Apply `/core:anti-fabrication` rules to all outputs produced with this skill active.