ArcavenAE/marvel

A kubernetes-like control plane for AI agent workloads. Manages the full
lifecycle of BYOA (Bring Your Own Agent) sessions: scheduling, configuration,
process management, health monitoring, and rolling shifts.
Where kubernetes orchestrates containers across nodes, marvel orchestrates
agent sessions across tmux panes.
Install
Option 1: Homebrew
The tap's marvel formula currently tracks the latest alpha release. A dedicated stable formula will be added when the first v* release ships.
Option 2: Install with mise
mise is a polyglot version manager. It reads a per-project mise.toml, pulls the binary directly from GitHub Releases, and verifies GitHub Artifact Attestations natively — no Homebrew tap required.
**Alpha channel** (prereleases from main) — the first stable release is pending, so opt into prereleases per-tool:
**Stable** (when a v* release ships) — drop the prerelease = true flag:
Marvel's alpha assets are not -a-suffixed, so stable and alpha share the same marvel shim — mise pins one version at a time per mise.toml, and switching channels swaps the underlying binary.
**macOS troubleshooting** — if a quarantine-aware host copies the mise install and Gatekeeper blocks launch, clear the xattr once:
Option 3: Download a pre-built binary
Download the latest release from GitHub Releases. Binaries are available for macOS (arm64, amd64) and Linux (amd64, arm64 — Raspberry Pi 3/4/5 64-bit, AWS Graviton, etc.). macOS binaries are code-signed and Apple-notarized.
Quick Start
Resource Model
A team contains heterogeneous roles. A review team might have 1 supervisor,
3 reviewers, and 1 architect — each with its own runtime, replica count,
restart policy, and healthcheck config.
Manifests
Resources are declared in TOML manifests:
image names the harness and is what selects the runtime adapter; marvel
falls back to command when it is unset, and a name matching no adapter
resolves to the generic one. Every adapter puts the session's identity in the
environment (MARVEL_SESSION, MARVEL_ROLE, MARVEL_TEAM,
MARVEL_WORKSPACE), so no role passes its own identity flags. The claude
adapter additionally names the session in the system prompt, unless the role
already passes its own --append-system-prompt or its command is a wrapper
around the harness (anything other than claude by name or path), which then
owns the prompt. Runnable manifests live in
examples/.
CLI
stop defaults to detach: the daemon checkpoints state and exits while
agents keep running; the next marvel daemon adopts the live panes. Use
--teardown to end every agent and leave the machine clean.
marvel events includes agent.* events (session start/end with cost and
timing, tool calls, permission prompts) for runtimes marvel can observe,
today a headless stream-json launch (see examples/claude-headless.toml).
Shifts
Shifts are rolling replacements of agent sessions. Agent sessions accumulate
context, drift, and stale mental models. A shift starts fresh sessions,
verifies they're running, then drains the old ones — preserving team identity.
Sessions track their generation (visible in marvel get sessions as the GEN
column). During a shift, old-generation sessions drain one per reconciliation