mngr: run any coding agent in parallel, anywhere

Built on SSH, git, and tmux. Extensible via plugins . No managed service required.

installation:

curl -fsSL https://raw.githubusercontent.com/imbue-ai/mngr/main/scripts/install.sh | bash

Overview

mngr makes it easy to create and use any AI agent (ex: Claude Code, Codex), anywhere (locally, in Docker, on Modal, etc.).

Think of mngr as "git for agents": just like git allows you to commit/push/pull/fork/clone versions of code, mngr allows you to create/destroy/list/clone/message agents.

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#EFF6FF', 'primaryTextColor': '#1E3A5F', 'primaryBorderColor': '#3B82F6', 'lineColor': '#64748B', 'edgeLabelBackground': '#FFFFFF', 'fontSize': '15px', 'wrap': false}, 'flowchart': {'diagramPadding': 150, 'curve': 'linear', 'markdownAutoWrap': false, 'wrappingWidth': 1800}}}%%
flowchart TB
    classDef user fill:#DBEAFE,stroke:#2563EB,stroke-width:2px,color:#1E3A5F,font-weight:bold
    classDef cli fill:#1E3A5F,stroke:#1E3A5F,stroke-width:2px,color:#FFFFFF,font-weight:bold
    classDef agent fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#064E3B
user([You]):::user
subgraph host1["Local Host"]
        direction LR
        style host1 fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F
        cli["mngr CLI ( create / list / connect / message / push / pull / snapshot / migrate / clone / destroy )"]:::cli
        agent1["OpenCode"]:::agent
        agent6["Codex"]:::agent
        subgraph docker1["Docker container 1"]
            direction LR
            style docker1 fill:#EDE9FE,stroke:#7C3AED,stroke-width:2px,color:#4C1D95
            agent3["Claude"]:::agent
            agent4["Claude"]:::agent
        end
        subgraph docker2["Docker container 2"]
            direction LR
            style docker2 fill:#EDE9FE,stroke:#7C3AED,stroke-width:2px,color:#4C1D95
            agent5["Claude"]:::agent
        end
    end
subgraph host2["Remote host 1"]
        direction LR
        style host2 fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F
        agent2["Claude"]:::agent
    end
subgraph host3["Remote host 2"]
        direction LR
        style host3 fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F
        agent7["Codex"]:::agent
        agent8["Claude"]:::agent
    end
user --> cli
    cli --> agent1
    cli --> agent6
    cli --> agent3
    cli --> agent4
    cli --> agent5
    cli --> agent2
    cli --> agent7
    cli --> agent8

Why mngr

Most agent tooling is a managed cloud: opaque infrastructure, per-seat pricing, hard to script.

mngr takes the opposite approach. Agents run on compute you control, that you access via SSH, and that shuts down when idle. It's built on primitives you already know (SSH, git, tmux, docker), and

mngr is designed to be:

• Simple — one command launches an agent locally or on Modal; sensible defaults throughout
• Fast — agents start in under 2 seconds
• Cost-transparent — free CLI; agents auto-shutdown when idle; pay only for inference and compute
• Secure — SSH key isolation, network allowlists, full container control
• Composable — shared hosts, snapshot and fork agent state, direct exec, push/pull/pair
• Observable — transcripts, direct SSH, programmatic messaging
• Easy to learn — mngr ask answers usage questions without leaving the terminal

mngr is very simple to use:

mngr create           # launch an agent locally (provider=local, project=current dir)
mngr create @.modal          # launch an agent on Modal (new host with auto-generated name)
mngr create my-task          # launch an agent with a name
mngr create my-task codex    # launch codex instead of the default
mngr create -- --model opus  # pass any arguments through to the underlying agent
send an initial message so you don't have to wait around:
mngr create --no-connect --message "Speed up one of my tests and make a PR on github"
or, be super explicit about all of the arguments:
mngr create [email protected] --type claude
tons more arguments for anything you could want! Learn more via --help
mngr create --help
or see the other commands--list, destroy, message, connect, push, pull, clone, and more!
mngr --help

mngr is fast:

> time mngr create local-hello  --message "Just say hello" --no-connect
Done.

real    0m1.472s
user    0m1.181s
sys     0m0.227s
> time mngr list
NAME           STATE       HOST        PROVIDER    HOST STATE  PROJECT
local-hello    RUNNING     localhost   local       RUNNING     mngr
real    0m1.773s
user    0m0.955s
sys     0m0.166s

mngr is free, and the cheapest way to run remote agents (they shut down when idle):

mngr create @.modal --no-connect --message "just say 'hello'" --idle-timeout 60 -- --model sonnet
costs $0.0387443 for inference (using sonnet)
costs $0.0013188 for compute because it shuts down 60 seconds after the agent completes

mngr takes security and privacy seriously:

# by default, cannot be accessed by anyone except your modal account (uses a local unique SSH key)
mngr create [email protected]
you (or your agent) can do whatever bad ideas you want in that container without fear
mngr exec example-task "rm -rf /"
you can block all outgoing internet access
mngr create @.modal -b offline
or restrict outgoing traffic to certain IPs
mngr create @.modal -b cidr-allowlist=203.0.113.0/24

mngr is powerful and composable:

# start multiple agents on the same host to save money and share data
mngr create [email protected] --new-host
mngr create agent-2@shared-host
run commands directly on an agent's host
mngr exec agent-1 "git log --oneline -5"
never lose any work: snapshot and fork the entire agent states
mngr create [email protected]
SNAPSHOT=$(mngr snapshot create doomed-agent --format "{id}")
mngr message doomed-agent "try running 'rm -rf /' and see what happens"
mngr create new-agent --snapshot $SNAPSHOT

mngr makes it easy to see what your agents are doing:

# programmatically send messages to your agents and see their chat histories
mngr message agent-1 "Tell me a joke"
mngr transcript agent-1

mngr makes it easy to work with remote agents:

mngr connect my-agent       # directly connect to remote agents via SSH for debugging
mngr rsync my-agent ./       # rsync changes from an agent to your local machine
mngr rsync ./ my-agent       # rsync your changes to an agent
mngr git pull my-agent       # pull git commits from an agent
mngr git push my-agent       # push git commits to an agent
mngr pair my-agent           # or sync changes continuously!

mngr is easy to learn:

> mngr ask "How do I create a container on modal with custom packages installed by default?"
Simply run:
    mngr create @.modal -b "--file path/to/Dockerfile"

Installation

Quick install:

curl -fsSL https://raw.githubusercontent.com/imbue-ai/mngr/main/scripts/install.sh | bash

Manual install (requires uv and core system deps: git, tmux, jq; optional: ssh, rsync, unison, claude):

uv tool install imbue-mngr

or run without installing
uvx --from imbue-mngr mngr

Upgrade:

uv tool upgrade imbue-mngr

For development:

git clone [email protected]:imbue-ai/mngr.git && cd mngr && uv sync --all-packages

To run the Imbue Studio desktop app from source on Linux, one script installs its prerequisites (Docker, uv, the pinned Node and pnpm) and launches it; see apps/minds/docs/dev-setup.md:

curl -fsSL https://raw.githubusercontent.com/imbue-ai/mngr/main/apps/minds/scripts/install-linux.sh | bash

Shell completion

mngr supports tab completion for commands, options, agent names, and -S/--setting config overrides (both the KEY and, where the value is constrained, the VALUE) in bash and zsh. Shell completion is configured automatically by the install script (scripts/install.sh), or interactively via mngr extras completion.

Your rc file gets only a small, stable shim that sources a managed completion file mngr keeps up to date, so completion improvements apply automatically when you upgrade mngr -- no need to re-edit your rc. If you have an older self-contained completion function in your rc, tab completion will nudge you to run mngr extras completion once to switch to the shim.

To set up manually, append the shim to your shell rc file (this also writes the managed completion file):

Zsh (run once):

uv tool run --from imbue-mngr python3 -m imbue.mngr.cli.complete --script zsh >> ~/.zshrc

Bash (run once):

uv tool run --from imbue-mngr python3 -m imbue.mngr.cli.complete --script bash >> ~/.bashrc

Note: mngr must be installed on your PATH for completion to work (not invoked via uv run).

Commands

# without installing:
uvx --from imbue-mngr mngr <command> [options]
if installed:
mngr <command> [options]

For managing agents:

• create: Create and run an agent in a host
• destroy: Stop an agent (and clean up any associated resources)
• connect: Attach to an agent

• list: List active agents
• stop: Stop an agent
• start: Start a stopped agent
• snapshot [experimental]: Create a snapshot of a host's state
• exec: Execute a shell command on an agent's host
• rename: Rename an agent
• clone: Create a copy of an existing agent
• migrate: Move an agent to a different host
• limit: Configure limits for agents and hosts
• docker: Docker-provider-specific commands (resize a container's CPU and memory caps)
• lima: Lima-provider-specific commands (resize a VM's CPUs, memory, and data disk)

For moving data in and out:

• rsync: Rsync files between local and a remote host or agent
• git: Push or pull git commits between local and a remote host or agent
• pair: Continually sync data with an agent
• message: Send a message to an agent
• transcript: View the message transcript for an agent

For maintenance:

• cleanup: Clean up stopped agents and unused resources
• event: View agent and host event files
• gc: Garbage collect unused resources

For managing mngr itself:

• ask: Chat with mngr for help
• plugin [experimental]: Manage mngr plugins
• config: View and edit mngr configuration

How it works

You can interact with mngr via the terminal (run mngr --help to learn more).

mngr uses robust open source tools like SSH, git, and tmux to run and manage your agents:

• agents are simply processes that run in tmux sessions, each with their own work_dir (working folder) and configuration (ex: secrets, environment variables, etc)
• agents run on hosts--either locally (by default), or special environments like Modal Sandboxes (--provider modal) or Docker containers (--provider docker). Use the agent@host address syntax to target an existing host.
• multiple agents can share a single host.
• hosts come from providers (ex: Modal, AWS, docker, etc)
• hosts help save money by automatically "pausing" when all of their agents are "idle". See idle detection for more details.
• hosts automatically "stop" when all of their agents are "stopped"
• mngr is extensible via plugins--you can add new agent types, provider backends, CLI commands, and lifecycle hooks

Architecture

mngr stores very little state (beyond configuration and local caches for performance), and instead relies on conventions:

• any process running in window 0 of a mngr- prefixed tmux sessions is considered an agent
• agents store their status and logs in a standard location (default: $MNGR_HOST_DIR/agents//)
• all hosts are accessed via SSH--if you can SSH into it, it can be a host
• ...and more

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#EFF6FF', 'primaryTextColor': '#1E3A5F', 'primaryBorderColor': '#3B82F6', 'lineColor': '#64748B', 'edgeLabelBackground': '#FFFFFF', 'fontSize': '15px'}}}%%
flowchart TB
    classDef transport fill:#DBEAFE,stroke:#2563EB,stroke-width:2px,color:#1E3A5F,font-weight:bold
    classDef session fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F
    classDef agent fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#064E3B
    classDef storage fill:#EDE9FE,stroke:#7C3AED,stroke-width:2px,color:#4C1D95
ssh["SSH (any SSH-accessible machine)"]:::transport
subgraph HOST["Host"]
        subgraph TMUX["tmux session: mngr-name"]
            w0["window 0 → agent process"]:::agent
            w1["window 1+ (optional)"]:::session
        end
        dir["$MNGR_HOST_DIR/agents/id/ · status · logs · config"]:::storage
    end
ssh --> HOST
    w0 -->|writes| dir

See architecture.md for an in-depth overview of the mngr architecture and design principles.

Security

Best practices:

1. Use providers with good isolation (like Docker or Modal) when working with agents, especially those that are untrusted.
2. Follow the "principle of least privilege": only expose the minimal set of API tokens and secrets for each agent, and restrict their access (eg to the network) as much as possible.
3. Avoid storing sensitive data in agents' filesystems (or encrypt it if necessary).

Sub-projects

This is a monorepo that contains the code for mngr here:

• libs/mngr/

• libs/mngr_modal/
• libs/mngr_claude/
• libs/mngr_robinhood/
• libs/mngr_pair/
• libs/mngr_opencode/
• libs/mngr_antigravity/

• libs/concurrency_group: a simple Python library for managing synchronous concurrent primitives (threads and processes) in a way that makes it easy to ensure that they are cleaned up.
• libs/imbue_common: core libraries that are shared across all of our projects
• apps/minds: an experimental project around scheduling runs of autonomous agents

Contributing

Contributions are welcome!