mng 0.1.1

Library for managing AI coding agents across different hosts

mng: build your team of AI engineering agents

installation:

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

mng is very simple to use:

mng                  # launch claude locally (defaults: command=create, agent=claude, provider=local, project=current dir)
mng --in modal       # launch claude on Modal
mng my-task          # launch claude with a name
mng my-task codex    # launch codex instead of claude
mng -- --model opus  # pass any arguments through to the underlying agent

# send an initial message so you don't have to wait around:
mng --no-connect --message "Speed up one of my tests and make a PR on github"

# or, be super explicit about all of the arguments:
mng create --name my-task --agent-type claude --in modal

# tons more arguments for anything you could want! Learn more via --help
mng create --help

# or see the other commands--list, destroy, message, connect, push, pull, clone, and more!
mng --help

mng is fast:

> time mng local-hello  --message "Just say hello" --no-connect --in local
# (time results)

> time mng remote-hello --message "Just say hello" --no-connect --in modal
# (time results)

> time mng list
# (time results)

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

mng create --in modal --no-connect --message "just say 'hello'" --idle-timeout 60 -- --model sonnet
# costs $0.001 for inference
# costs $0.0001 for compute because it shuts down 60 seconds after the agent completes

mng takes security and privacy seriously:

# by default, cannot be accessed by anyone except your modal account (uses a local unique SSH key)
mng create example-task --in modal

# you (or your agent) can do whatever bad ideas you want in that container without fear
mng exec example-task "rm -rf /"

# you can block all outgoing internet access
mng create --in modal -b offline

# or restrict outgoing traffic to certain IPs
mng create --in modal -b cidr-allowlist=203.0.113.0/24

mng is powerful and composable:

# start multiple agents on the same host to save money and share data
mng create agent-1 --in modal --host-name shared-host
mng create agent-2 --host shared-host

# run commands directly on an agent's host
mng exec agent-1 "git log --oneline -5"

# never lose any work: snapshot and fork the entire agent states
mng create doomed-agent --in modal
SNAPSHOT=$(mng snapshot doomed-agent --format "{id}")
mng message doomed-agent "try running 'rm -rf /' and see what happens"
mng create new-agent --snapshot $SNAPSHOT

mng makes it easy to work with remote agents

mng connect my-agent       # directly connect to remote agents via SSH for debugging
mng pull my-agent          # pull changes from an agent to your local machine
mng push my-agent          # push your changes to an agent
mng pair my-agent          # or sync changes continuously!

mng is easy to learn:

> mng ask "How do I create a container on modal with custom packages installed by default?"

Simply run:
    mng create --in modal --build-arg "--dockerfile path/to/Dockerfile"

Overview

mng makes it easy to create and use any AI agent (ex: Claude Code, Codex), whether you want to run locally or remotely.

mng is built on open-source tools and standards (SSH, git, tmux, docker, etc.), and is extensible via plugins to enable the latest AI coding workflows.

Installation

Quick install (installs system dependencies + mng automatically):

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

Manual install (requires uv and system deps: git, tmux, jq, rsync, unison):

uv tool install mng

# or run without installing
uvx mng

Upgrade:

uv tool upgrade mng

For development:

git clone [e-mail]:imbue-ai/mngr.git && cd mngr && uv sync --all-packages && uv tool install -e libs/mng

Shell Completion

mng supports tab completion for commands and agent names in bash, zsh, and fish.

Zsh (add to ~/.zshrc):

eval "$(_MNG_COMPLETE=zsh_source mng)"

Bash (add to ~/.bashrc):

eval "$(_MNG_COMPLETE=bash_source mng)"

Fish (run once):

_MNG_COMPLETE=fish_source mng > ~/.config/fish/completions/mng.fish

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

Commands

# without installing:
uvx mng <command> [options]

# if installed:
mng <command> [options]

For managing agents:

• create: (default) Create and run an agent in a host
• list: List active agents
• connect: Attach to an agent

• stop: Stop an agent
• start: Start a stopped agent
• snapshot [experimental]: Create a snapshot of a host's state
• destroy: Stop an agent (and clean up any associated resources)
• 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

For moving data in and out:

• pull: Pull data from agent
• push: Push data to agent
• pair: Continually sync data with an agent
• message: Send a message to an agent
• provision: Re-run provisioning on an agent (useful for syncing config and auth)

For maintenance:

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

For managing mng itself:

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

How it works

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

mng 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 (--in modal) or Docker containers (--in docker). Use --host <name> 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"
• mng is extensible via plugins--you can add new agent types, provider backends, CLI commands, and lifecycle hooks

Architecture

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

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

See architecture.md for an in-depth overview of the mng 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).

See ./docs/security_model.md for more details on our security model.

Contributing

Contributions are welcome!