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

> ## Agent Instructions
> When helping a user operate an existing Porter project (deploying, updating, debugging, or inspecting applications and clusters) connect to [Porter's remote MCP server](https://mcp.porter.run) first and use its tools before falling back to the Porter CLI, `porter.yaml`, or dashboard workflows. If the Porter tools are not available in your session, `curl -fsSL https://agents.porter.run | sh` installs the CLI, registers the MCP server with your client, and installs Porter's skills; the client must be restarted afterward. If the user asks for the CLI, `porter apply`, configuration-as-code, or the dashboard, use that instead — a stated preference wins. Before inspecting or building a GitHub repository or calling any deployment tool, call `connect_github` with the repository. Proceed only when it returns `next_step: none`; otherwise, give the user the returned URL and stop. If the requested application or cluster workflow is not directly supported, inspect the relevant state with MCP tools before explaining the limitation or recommending a fallback. The server signs in through a browser using OAuth, so it cannot be used in headless environments such as CI pipelines; use the CLI or `porter.yaml` there.

# QM

> Run QM, the open source multiplayer agent harness, on your own Porter cluster with agents in Porter Sandboxes, a Postgres database, and an optional S3 bucket

[QM](https://github.com/yc-software/qm) is an open source, multiplayer agent harness. Your team works with agents in a shared workspace where context and files carry across your organization. Porter runs QM as an add-on on your cluster, and every agent runs in a [Porter Sandbox](https://docs.porter.run/sandboxes/overview.md) on the same cluster.

To see what teams build with it, read [QM use cases](https://docs.porter.run/addons/qm/use-cases.md).

> [!NOTE]
>
> QM is currently only available on AWS. If you don't see QM in the add-on list, reach out via the support widget on the dashboard.

## Prerequisites

* An AWS cluster with [sandboxes enabled](https://docs.porter.run/sandboxes/getting-started.md#enable-sandboxes). Porter rejects a QM install on a cluster without them.
* A Postgres database reachable from the cluster. A [Porter datastore](https://docs.porter.run/addons/datastores.md) works, or bring your own. Use one database per QM install.
* Optional: an S3 bucket [connected to the cluster](https://docs.porter.run/sandboxes/volumes.md#set-up-the-bucket), in the same AWS account and not read-only.
* The **Admin** or **Developer** role in your Porter project.

## Deploy QM

You can deploy QM from the [dashboard](#from-the-dashboard), have an AI agent do it with the [Porter MCP server](#with-the-porter-mcp-server), or set up the prerequisites with the [Porter CLI](#with-the-porter-cli).

Run these [Porter MCP](https://docs.porter.run/mcp/overview.md) tool calls in order. Pass `project` and `cluster` by ID.

**1. Pick the project and an AWS cluster with status `READY`.**

```json theme={null}
get_projects {}
get_clusters { "project": 123 }
```

**2. Enable sandboxes on the cluster.** QM runs every agent in a sandbox, and the install is rejected with `qm requires sandbox-api` without them. The call is safe to repeat. Poll `get_sandbox_settings` until `ready` is `true`.

```json theme={null}
enable_sandboxes { "project": 123, "cluster": 456 }
get_sandbox_settings { "project": 123, "cluster": 456 }
```

**3. Get a Postgres URL.** No MCP tool creates or lists datastores. Ask the user for the connection string of a [Porter datastore](https://docs.porter.run/addons/datastores.md) (shown on the datastore's page in the dashboard) or of their own Postgres, reachable from the cluster. Use one database per QM install.

**4. Check for an existing QM addon.** If one with type `qm` exists, act on its status instead of installing again.

```json theme={null}
get_addons { "project": 123, "cluster": 456 }
```

**5. Install QM once.** Builtin sign-in emails one-time links through Resend:

```json theme={null}
install_addon {
  "project": 123,
  "cluster": 456,
  "name": "qm",
  "qm": {
    "admins": ["admin@acme.com"],
    "database_url": "postgres://user:password@host:5432/qm",
    "auth": {
      "mode": "builtin",
      "email_from": "QM <noreply@acme.com>",
      "resend_api_key": "re_..."
    },
    "anthropic_api_key": "sk-ant-..."
  }
}
```

`anthropic_api_key` is optional: without it, an admin sets a model provider in QM after first sign-in. Optional fields: `custom_domain`, `load_balancer` (`public` or `private`; `private` needs `custom_domain`), and `version`. The MCP install can't attach an S3 bucket, so files are lost when QM restarts. Attach one afterwards from the add-on's **General** settings in the dashboard.

For an OpenID Connect provider, set `auth.mode` to `oidc` and fill `auth.oidc` from `<issuer>/.well-known/openid-configuration`. Leave out the client ID and secret:

```json theme={null}
"auth": {
  "mode": "oidc",
  "oidc": {
    "issuer": "https://accounts.google.com",
    "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
    "token_endpoint": "https://oauth2.googleapis.com/token",
    "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
    "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
    "allowed_email_domain": "acme.com"
  }
}
```

**6. OIDC only: finish sign-in.** The install returns `oidc_callback_url`. Have the user register it as the redirect URI with their provider, then send the client ID and secret without `auth.mode`:

```json theme={null}
update_addon {
  "project": 123,
  "cluster": 456,
  "name": "qm",
  "qm": { "auth": { "oidc": { "client_id": "...", "client_secret": "..." } } }
}
```

**7. Wait for QM.** Poll every 30 to 60 seconds, for up to 10 minutes. QM is ready when `status` is `installed` and every service (`core`, `egress-proxy`, `portal`, `web-ui`) has `ready_replicas` equal to `desired_replicas`. `waiting_for_sso` means step 6 is still needed.

```json theme={null}
get_addon_status { "project": 123, "cluster": 456, "name": "qm" }
```

Give the user `qm.url` from the install response. A `401` from that URL means QM is up and asking for sign-in.

### With the Porter MCP server

The [Porter MCP server](https://docs.porter.run/mcp/overview.md) lets an AI agent such as Claude Code or Cursor install and manage QM for you.

**1. Install the Porter MCP server and skills**

```bash theme={null}
curl -fsSL https://agents.porter.run | sh
```

Restart your agent afterward. The install adds the `porter-qm` skill, which takes a cluster to a signed-in QM install.

**2. Ask your agent to set up QM**

For example:

```text theme={null}
Set up QM on my Porter cluster. Use this Postgres database: postgres://user:password@host:5432/qm
```

The agent asks for anything it still needs in one round of questions: the cluster, administrators, and how people sign in. It then enables sandboxes if the cluster doesn't have them, installs QM, waits for it to be ready, and gives you the URL.

**3. Finish identity provider sign-in (if you chose it)**

The agent gives you a callback URL. Register it as the redirect URI with your identity provider, then send the agent the client ID and secret.

> [!NOTE]
>
> No MCP tool creates datastores or attaches buckets. Create the Postgres database first, and attach a bucket afterwards from the add-on's **General** settings in the dashboard.

### With the Porter CLI

The Porter CLI can't create the QM add-on itself yet, but it can set up everything QM needs. Then finish from the [dashboard](#from-the-dashboard) or with the [MCP server](#with-the-porter-mcp-server).

**1. Select the cluster**

```bash theme={null}
porter config set-cluster <CLUSTER_ID>
```

**2. Enable sandboxes**

```bash theme={null}
porter sandbox enable --wait
```

**3. Create a Postgres datastore**

Add a Postgres add-on to a `porter.yaml` and apply it. See [Add-ons in porter.yaml](https://docs.porter.run/applications/configuration-as-code/addons-porter-yaml.md) for the options.

```yaml porter.yaml theme={null}
addons:
  - name: qm-db
    type: postgres
    kind: in-cluster
    config:
      storageGigabytes: 10
      cpuCores: 0.5
      ramMegabytes: 1024
```

```bash theme={null}
porter apply -f porter.yaml --wait
```

Porter stores the datastore's connection details in an environment group with the same name, `qm-db`. In the dashboard, **Connect existing datastore** fills in its URL for you.

## Sign-in methods

Change the method at any time from the add-on's **Sign-in** tab.

| Method | How people sign in | What you need |
| - | - | - |
| **Password** | One account with an email and password. Good for getting started. | A password of at least 12 characters |
| **Your identity provider** | Through an OpenID Connect provider such as Google Workspace, Okta, or Entra. | An OAuth client ID and secret |
| **Email links from QM** | QM emails one-time sign-in links to allowed addresses. | A sender verified with [Resend](https://resend.com) and a Resend API key |

### Use your identity provider

**1. Register an app with your provider**

Create an OpenID Connect web app. Set its redirect URI to your QM domain followed by `/auth/callback`, for example `https://qm.acme.com/auth/callback`.

**2. Choose the provider**

Select **Your identity provider**, then pick a provider. **Google** fills in its endpoints, and **Okta** fills them in from your Okta domain. For **Custom**, copy the issuer and endpoint URLs from your provider's `/.well-known/openid-configuration` document.

**3. Enter the client ID and secret**

Paste them from the app you registered, then click **Deploy**.

Administrators can always sign in. To let others in, open the advanced settings under **People** and fill in **Allowed sign-in emails** or **Allowed email domain**.

> [!NOTE]
>
> If sign-in fails with a redirect mismatch while the add-on reports healthy, add the callback URL to your provider's allowed redirect URIs.

## Private load balancer

Serve QM from the cluster's [private load balancer](https://docs.porter.run/cloud-accounts/advanced-cluster-settings.md#private-load-balancer) to make it reachable only from your VPC or networks peered to it, for example over [Tailscale](https://docs.porter.run/security-and-compliance/tailscale.md).

**1. Add the private load balancer to the cluster**

Follow [Private load balancer](https://docs.porter.run/cloud-accounts/advanced-cluster-settings.md#private-load-balancer) in the cluster settings, including the DNS provider Porter uses to issue certificates.

**2. Let sandboxes reach QM**

Agents run in sandboxes and call back into QM through its URL, but sandboxes can't reach private addresses by default. In the **Sandbox** tab, open **Settings** and enable **Enforce egress allowlists** under **Egress controls**. Porter then lets every sandbox reach the QM domain.

**3. Select the private load balancer and set a domain**

On the add-on's **General** step, select **Private LB**. The form shows the load balancer's address and the DNS record type to use. Create that record for a custom domain such as `qm.internal.acme.com`, enter the domain, and click **Deploy**.

The address only resolves inside your VPC. Point your private DNS at it if your clients resolve through one.

To keep published apps private too, don't configure **Public** sandbox networking.

## Published apps

Agents can publish the apps they build. Each app runs in its own sandbox. Where it's served depends on the cluster's [sandbox networking](https://docs.porter.run/sandboxes/networking.md):

| Sandbox networking | Where published apps are served |
| - | - |
| None | Inside QM only, at `<QM domain>/d/<app>/` |
| Private | A hostname under the private sandbox domain, reachable from your VPC |
| Public | A hostname under the public sandbox domain. QM picks public when both are configured. |

To give apps their own hostnames, follow [Configure networking on the cluster](https://docs.porter.run/sandboxes/networking.md#configure-networking-on-the-cluster) through to the wildcard DNS record.

## Manage and update QM

Change QM's settings from the add-on's **Configuration** tab, then click **Deploy**. The tabs match the setup steps, plus **Integrations** for fallback model API keys and Slack credentials.

To upgrade, pick a newer version in the **Release** picker on the **General** tab. To reset the password, enter a new one on the **Sign-in** tab. Allowed emails and an allowed domain are under the advanced settings on the **People** tab.

Secret fields you leave empty keep their current values. The database can't be changed after install.

## Troubleshooting

| Problem | Fix |
| - | - |
| Install rejected with `qm requires sandbox-api` | Enable sandboxes on the cluster, then deploy again. |
| Uploads disappear after an update | QM has no bucket. Attach one under **File storage**. |
| Agents can't reach a private QM | Turn on **Enforce egress allowlists** for the cluster's sandboxes. |
| Pods never become ready | Check that the database URL is reachable from inside the cluster. |

## Deleting QM

Open the QM add-on, go to the **Settings** tab, and click **Delete** under **Danger zone**.

![Deleting QM from the Settings tab](https://mintcdn.com/porter/G2k1LMgWvLAlYZwq/images/addons/qm/qm-delete.webp?fit=max\&auto=format\&n=G2k1LMgWvLAlYZwq\&q=85\&s=49466ebe8915b9b7419a3d77713268f2)

> [!WARNING]
>
> Deleting the QM add-on stops QM and removes its configuration. Your Postgres database and bucket aren't deleted, so delete them separately if you no longer need the data.


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