# Overview

`mng` is a CLI for creating and managing AI coding agents — locally or in the cloud.

You give it a task and a destination. It handles provisioning the environment, running the agent, managing its lifecycle, and shutting things down when the work is done. You stay in your terminal.

***

## The problem

AI coding agents like Claude Code and Codex are useful when they're running. Getting them running — and keeping them running well — is harder than it should be.

Running an agent locally ties up your machine and means you can only do one thing at a time. Running one remotely means setting up cloud infrastructure, managing SSH access, handling costs, and figuring out how to get your files in and out. There's no standard way to start an agent, check its status, send it a message, or shut it down. Every provider has a different interface.

`mng` solves this by treating agents as a first-class primitive: things you can create, list, connect to, message, snapshot, and destroy — regardless of where they're running.

***

## What mng does

**Runs agents anywhere.** Local, Docker, or Modal — same commands either way. Specify a provider in the agent address and `mng` handles the rest.

```bash
mng create my-task              # runs locally
mng create my-task@.modal       # runs on Modal
mng create my-task@.docker      # runs in Docker
```

**Manages the full lifecycle.** Create, stop, start, destroy, list — all from one CLI. Agents are just processes in tmux sessions, so they're easy to inspect and understand.

**Shuts down when idle.** Remote hosts automatically stop when the agent finishes, so you're not paying for a running sandbox after the work is done.

```bash
mng create my-task@.modal --idle-timeout 300 --no-connect \
  --message "Fix the N+1 query in the users endpoint and open a PR."
```

**Keeps your files in sync.** Push your local changes to a remote agent, pull its work back, or run a continuous bidirectional sync while you collaborate in real time.

**Snapshots full environment state.** Capture the complete filesystem of a remote host — not just the git state — so you can fork from a known-good point if something goes wrong.

**Built on open standards.** SSH, git, tmux, Docker. If you can SSH into it, it can be a host. No proprietary agents, no lock-in.

***

## Installation

**Quick install** (handles system dependencies automatically):

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

**Manual install** (requires [uv](https://docs.astral.sh/uv/), `git`, `tmux`, `jq`, `rsync`):

```bash
uv tool install mng
```

***

## Core concepts

* **Agents** are processes running in tmux sessions, each with their own working directory and configuration.
* **Hosts** are the machines agents run on — local, a Modal sandbox, a Docker container, or any SSH-accessible server.
* **Providers** create and manage hosts (Modal, Docker, local, SSH).

Multiple agents can share a single host, which saves cost and lets them read each other's files directly.

***

## Use cases

* [Parallel agents on a shared host](https://docs.imbue.com/mng/use-cases/parallel-agents-shared-host) — run multiple agents simultaneously on one Modal sandbox to split up a feature and cut costs
* [Fire-and-forget tasks](https://gitlab.com/generally-intelligent/mng/-/blob/main/use-cases/fire-and-forget-tasks.md) — delegate a well-scoped task, walk away, and let the host shut itself down when done
* [Safe large refactors with snapshots](https://docs.imbue.com/mng/use-cases/safe-refactors-with-snapshots) — checkpoint before a risky migration and fork if it goes wrong

***

## Quick reference

```bash
mng create my-agent             # launch an agent (connects by default)
mng list                        # see all running agents
mng connect my-agent            # attach to an agent's terminal
mng message my-agent "..."      # send a message to a running agent
mng exec my-agent "git status"  # run a command on the agent's host
mng destroy my-agent            # stop and clean up

mng --help                      # full command reference
```