MixumART

An early host-side runtime for agents that need a real machine.

The host-side runtime for agents that need a real machine: one Tauri app and one CLI that turn
Apple Container, Docker or WSL 2 into a disposable, inspectable mixumOS environment.

简体中文 · English

Status: v0.1.0, alpha. This is an early, unfinished build. The macOS + Apple Container path is the one we use daily; Docker and WSL 2 are implemented but not equally exercised. APIs will move. Packaging is deliberately rough — see the alpha notes.

The problem

Calling an API is not the same as using a computer.

Agents increasingly need to install packages, run a browser, click through a desktop app, recover from a bad command, and hand the whole session to a human. Hosted sandboxes tend to be black boxes; bare container CLIs leave too much to assemble. We wanted a real machine with a desktop, managed from the host and driven by an agent — so we built one, imperfectly.

MixumART is the host-side layer that closes that gap. It does not reimplement the sandbox: it consumes mixumOS and speaks MAP. It owns the part that must live on your laptop: runtime discovery, environment lifecycle, credentials, ports, windows and the control plane agents talk to.

What it does today

Why Rust

The same Rust workspace contains the runtime contract (mixum-env-core), the three backends, the MAP WSS client (mixum-env-map), the surface protocol (mixum-env-surface), the in-container compositor (mixum-env-compositor), the host-side display client and the CLI/daemon. That means:

• one Result/error model from CLI to GUI, with error codes stable enough for agents;
• no shell-string construction anywhere — process::run takes an argv vector and a timeout;
• platform differences isolated behind cfg(target_os) in the backend crates;
• the agent-facing commands (mixum --json, mixum mcp) and the GUI share exactly the same implementation, so they cannot drift.

Apple Container is a first-class backend

Apple Container is not "Docker with a different binary". It runs Linux containers inside lightweight VMs, with APFS clonefile sharing, a host-wide kernel setting, and its own CLI semantics. MixumART handles those differences explicitly:

• probes container system status and reports not installed vs not running as distinct states;
• chooses Apple Container first on macOS when no runtime is specified;
• publishes the MAP port to 127.0.0.1 only;
• reads the node's admin token through the local runtime, never from a file the user has to paste;
• understands the custom linux-mixum-micro kernel (CRIU/Landlock enabled) documented in mixumOS.

Measured on an M1 / 16 GB / macOS 26.6 with container 1.5.0: a full node (agentd + mixcomp) used ≈38 MiB of RAM, a second container from the same image added 0 MB of physical disk, and warm container start was ≈1.0 s. Those are mixumOS numbers; MixumART adds the host UI and control plane, not a second copy of the sandbox.

Architecture

flowchart TB
    subgraph Host["Host machine"]
        UI["MixumART desktop<br/>React 19 + Tauri 2"]
        CLI["mixum CLI<br/>--json · stable exit codes"]
        MCP["mixum mcp<br/>stdio MCP server"]
        D["mixum-artd<br/>Unix socket · 0600"]
        CORE["mixum-env-core<br/>RuntimeBackend contract"]
        UI --> CORE
        CLI --> CORE
        MCP --> CLI
        D --> CLI
        CORE --> A["Apple Container"]
        CORE --> DK["Docker"]
        CORE --> W["WSL 2"]
    end

    A --> N["mixumOS node<br/>agentd · :7601"]
    DK --> N
    W --> N
    N -->|"MAP over WSS<br/>TLS 1.3 + map1 token"| M["mixum-env-map"]
    M --> UI
    C["mixum-env-compositor<br/>inside the container"] -->|"PNG frames + damage<br/>over display.sock"| N

Both compositors are clients of the Node's display broker
(/run/mixum/display.sock). The broker is the only component that speaks MAP
over WSS to mixum-env-map; nothing inside the container reaches the host UI
directly.

Two display paths, one host

mixumOS can capture windows in two ways, and MixumART can show both at once:

• A — mixcomp capture. The compositor inside mixumOS captures each window and streams PNG damage patches by default, with JPEG/H.264 as fallbacks. The host shows one window per surface and labels the source A.
• B — MixumART compositor. mixum-env-compositor runs inside the container as a Smithay headless compositor and forwards each surface's buffer + damage. The host maintains the base texture and uploads only dirty regions. This path keeps text pixel-perfect and gives the host a surface tree.

The window page lists both, routes input to the correct owner, and lets you fall back to A per window. On macOS the B path is rendered by a native MTKView/Metal overlay; other platforms (or MIXUM_NATIVE_METAL=0) fall back to a WebView canvas with identical input handling.

Quick start

Prerequisites

On macOS with Apple Container, the host setup is two commands:

brew install container
container system start

Then pass --runtime apple to mixum env create. If more than one runtime is ready, the CLI requires an explicit --runtime.

1. Build the CLI and check the host

cargo build --release -p mixum-cli

./target/release/mixum doctor
./target/release/mixum runtime list

doctor prints the data directory, the three backends, their state and the port range. A missing runtime is a state, not an error: the CLI tells you what to install or start.

2. Create an environment

# The image must contain agentd, mixcomp and /entrypoint.sh,
# and its reference must contain "mixumos" for --profile mixumos.
./target/release/mixum env create \
  --profile mixumos \
  --title "fix login" \
  --image mixumos:0.1.5 \
  --runtime apple

./target/release/mixum env list
./target/release/mixum env windows "fix login"

The CLI picks a free host port in 17600–17999, publishes it on 127.0.0.1 only, waits for MAP, pins the certificate fingerprint and records the title in a local registry (0600). Use --profile generic for a plain container with no agentd and no window stream.

3. Open a window

# Read-only browser monitor for one surface; prints the URL.
# Omit --window when the environment has exactly one surface;
# otherwise take the id from `mixum env windows`.
./target/release/mixum env open "fix login" --no-open

# Or use the desktop app:
cd apps/desktop
npm install
npm run tauri dev

The desktop's Windows page connects over MAP WSS, lists surfaces from both A and B, opens one native window per surface, and supports Ctrl/Cmd+Shift+T takeover.

4. Give the agent the control plane

# stdio MCP server — one tool per safe operation.
./target/release/mixum mcp

Example client configuration:

{
  "mcpServers": {
    "mixum": {
      "command": "/absolute/path/to/mixum",
      "args": ["mcp"]
    }
  }
}

Tools exposed over MCP: mixum_env_list, mixum_env_create, mixum_env_show, mixum_env_windows, mixum_env_start, mixum_env_stop, mixum_snapshot_list, mixum_snapshot_create, mixum_port_check.

Terminal access, arbitrary shells and destructive snapshot restore are deliberately not exposed over MCP. The CLI still provides them locally, with --yes required for restore. The bundled agent instructions live in skills/mixum-art/SKILL.md.

5. Optional: a daemon for long-lived clients

./target/release/mixum-artd
# default socket: <data-dir>/artd.sock, mode 0600

The daemon speaks one JSON request per line and one JSON response per line, using the same error codes as the CLI. It shells out to the sibling mixum --json binary, so port allocation, state and MAP rules have exactly one implementation. See docs/daemon.md.

CLI at a glance

Every command supports --json; errors are machine-readable and exit codes are stable (0 ok, 1 IO, 2 usage, 3 not found, 4 conflict, 5 runtime, 6 MAP).

Full contract, selectors and JSON shapes: docs/cli.md.

Alpha notes

MixumART is alpha. The macOS app is unsigned (no Apple Developer Program yet),
Windows shows SmartScreen, and the browser bridge is developer-mode only until a
store listing exists. ALPHA.md has the exact steps and the reason;
none of this affects the CLI, Docker images, or the npm SDK.

Platform support

"Implemented" means the code path exists and compiles for that target. "Verified" means it was exercised on real hardware. We try to keep the distinction; admitting a gap is more useful than claiming coverage we have not exercised.

Security model

• No shell interpolation. Every external command is an argv vector with a timeout; the process layer refuses shell strings.
• Loopback only. The MAP port is published to 127.0.0.1; the browser monitor binds to loopback; the daemon socket is 0600 inside a 0700 data directory.
• Credentials stay local. Connection tokens and agent credentials go to the OS keychain. The CLI reads the node's admin token through the local runtime on demand and never prints it; env logs redacts map1.….
• Pin the node. MAP connections use TLS 1.3 and TOFU certificate pinning, stored per host in ~/.mixum/known-hosts (or the app data directory). A changed fingerprint is a hard failure.
• Least privilege in Tauri. The desktop only enables the capabilities it needs; platform logic stays in Rust, not in the webview.
• No telemetry in this build. MixumART does not phone home; there is no account and no update beacon. Any future opt-in analytics would be documented in the ecosystem TRUST commitments and off by default.

The full runtime contract and error mapping are in docs/runtime-contract.md; the display threat model is in docs/display.md.

Where we could be wrong

We are not sure the host/runtime split is the right boundary, that a native Metal
overlay is worth its complexity over a plain WebView, or that Docker and WSL 2 can
be supported to the same depth as Apple Container. Packaging is also rough: the
app is unsigned, and the browser bridge is developer-mode only.

If you have shipped a desktop runtime, a compositor or a cross-platform installer,
tell us what you would change first. We would rather hear it now.

Status and roadmap

Repository map

MixumART/
├── crates/
│   ├── mixum-env-core/           domain types, RuntimeBackend contract, timed process
│   ├── mixum-env-runtime-apple/  Apple Container backend
│   ├── mixum-env-runtime-docker/ Docker backend
│   ├── mixum-env-runtime-wsl2/   WSL 2 backend
│   ├── mixum-env-map/            MAP WSS client, TOFU, display/input
│   ├── mixum-env-surface/        surface/frame/input wire types
│   ├── mixum-env-compositor/     Smithay headless compositor (container side)
│   ├── mixum-env-display/        host TCP viewer / debug client
│   └── mixum-cli/                mixum, mixum-artd, MCP, browser monitor, PTY
├── apps/desktop/                 Tauri shell + React UI
├── skills/mixum-art/             agent-facing workflow
├── docs/                         architecture, CLI, daemon, display, contract, UI
└── Cargo.toml                    one workspace, three backends

Documentation

Most design documents are currently written in Chinese; the CLI/daemon contracts and the tests are the English-readable source of truth. Translation help is welcome.

Ecosystem

Contributing

cargo check --workspace --all-targets
cargo test --workspace
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings

cd apps/desktop && npm ci && npm run build

Keep platform differences inside crates/mixum-env-runtime-*. Do not add cfg(target_os) to mixum-env-core. Frontend commands go through src/api.ts; new Tauri commands must be registered in generate_handler!. See docs/contributing.md before opening a PR.

License

Apache-2.0. Third-party components keep their own licenses; see THIRD_PARTY_NOTICES.md.