> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How Monk works

> The pieces of Monk, who writes what, and the loop from a repository to a running app

Monk is the operations agent for your app, and you use it from your coding agent. Your coding agent reads and writes code. Monk plans, provisions, deploys and keeps track of what is running. The resources run in your own cloud account.

## The pieces

```text theme={"dark"}
 Your coding agent  (Claude Code, Codex, Cursor and others)
        │  Monk plugin, or a `monk` MCP server entry
        ▼
 monk-agent  (local companion, http://127.0.0.1:7419)
        │  MCP tools, local dashboard, vault for credentials
        ▼
 Monk orchestrator  (monkd, on your machine and on your cluster nodes)
        │
        ▼
 Your cloud account  (AWS, GCP, Azure, DigitalOcean, Hetzner) or your own machine
```

* **The plugin or MCP entry.** The [installer](/getting-started/installer) adds it to each coding agent it finds. See [Supported agents](/getting-started/agents).
* **The local companion (`monk-agent`).** A small server on your computer. It exposes Monk's tools to your coding agent over MCP. It also serves the [local dashboard](/getting-started/local-dashboard), where you review plans, approve changes and enter credentials.
* **The orchestrator (`monkd`).** It runs your workloads, on your machine in local mode or on the nodes of a cluster in your cloud account. It keeps the state of what it manages.
* **Your cloud account.** Machines, managed databases and other resources are created there, and your provider bills you for them directly.

## Who writes what

| Who | What it does |
| - | - |
| Your coding agent | Reads your code. Writes the Dockerfiles and Monk's `MANIFEST` and templates, through Monk's editor subagent where the host supports one. |
| Monk | Checks the configuration, shows the plan, provisions infrastructure, builds images, deploys, and reports status and logs. |
| You | Approve plans and other changes, and enter credentials in the local dashboard. |

Monk does not edit your application code. When code has to change before something will deploy, your coding agent makes that change, in the same way it makes any other code change.

## The loop

<Steps>
  <Step title="Analyze">
    Monk checks whether the project already has a `MANIFEST`. If it doesn't, your coding agent reads the repository to work out the services, their connections and the configuration they need.
  </Step>

  <Step title="Configure">
    Your coding agent writes the `MANIFEST`, the templates and any missing Dockerfiles. Before it writes services such as PostgreSQL or Redis by hand, it looks for an existing Monk package. Monk's analyzer checks the result.
  </Step>

  <Step title="Plan">
    Monk works out what a deploy would change: the workloads, any warnings and the cost impact. Nothing is built or created at this step.
  </Step>

  <Step title="Approve">
    The plan opens in the local dashboard. If credentials or secrets are missing, Monk asks for them there through a form. Nothing is created until you approve.
  </Step>

  <Step title="Deploy">
    Monk builds the images and starts the workloads, either locally or on the cluster. It then checks their status and readiness.
  </Step>
</Steps>

To start, ask:

```
/monk plan a deployment for this app
```

The two starting paths, [a new app](/guides/start-new-app) and [an app that's already running](/guides/deploy-existing-app), both follow this loop. For a running app, Monk builds new infrastructure from source alongside the original and leaves the original alone.

## The model Monk keeps

The orchestrator keeps a record of the workloads, entities, connections and cluster nodes it manages. That record doesn't depend on your chat history, so a new session can read the app's current state and status without being told how it was deployed. The deploy review in the local dashboard draws the planned app from the same model.

You can ask about it at any time:

```
/monk what's running in this project?
```

## Approvals and limits

Monk's tools check every request and the permissions behind it before acting. Actions that create, change or delete infrastructure ask for your approval in the local dashboard. [Security](/concepts/security) describes what Monk's tools can and can't do, and what your coding agent can do on its own.

## Related

<CardGroup cols={2}>
  <Card title="Talking to Monk" icon="comments" href="/guides/talking-to-monk">
    How to phrase requests and what Monk asks back
  </Card>

  <Card title="Deployments" icon="rocket" href="/concepts/deployments">
    MANIFEST, plans, redeploys and rollbacks
  </Card>

  <Card title="Security" icon="shield" href="/concepts/security">
    Credentials, approvals and what each tool can do
  </Card>

  <Card title="Local dashboard" icon="table-columns" href="/getting-started/local-dashboard">
    Where you review and approve
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.