> ## 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](/sandboxes/overview) on the same cluster.

<Info>
  QM is currently only available on AWS. If you don't see QM in the add-on list, please reach out via the support widget on the dashboard.
</Info>

## Install QM with an AI agent

The [Porter MCP server](/mcp/overview) can install and manage QM from an AI agent with the [add-on tools](/mcp/tools#add-ons). The [quick install](/mcp/overview#quick-install) also adds the `porter-qm` skill, which takes a cluster to a signed-in QM install and works through failures along the way.

Ask your agent to set up QM on Porter. It collects the inputs in one round of questions and then runs the install. If the cluster doesn't have sandboxes yet, it can enable them with `enable_sandboxes`.

***

## How it works

The QM add-on deploys these services to your cluster:

| Service | Description |
| - | - |
| **portal** | Serves the QM web app and handles sign-in. The only service exposed outside the cluster. |
| **web-ui** | The QM interface and admin console, served through the portal. |
| **core** | Runs agent turns and creates sandboxes through the in-cluster Sandbox API. |

Porter wires QM to the cluster for you: QM talks to the Sandbox API inside the cluster without an API token. Everything QM stores lives in your cloud account: its state in a Postgres database you provide, and its files in an optional S3 bucket.

***

## Prerequisites

* An AWS cluster with [sandboxes enabled](/sandboxes/getting-started#enable-sandboxes)
* A Postgres database reachable from the cluster
* Optional: an S3 bucket connected to the cluster
* Optional: public or private [sandbox networking](/sandboxes/networking#configure-networking-on-the-cluster) for published apps

<Note>
  Porter rejects a QM install on a cluster without sandboxes, since every agent runs in a sandbox.
</Note>

***

## Setup

<Steps>
  <Step title="Enable sandboxes">
    In the Porter Dashboard, navigate to the **Sandbox** tab for the AWS cluster where you want to run QM and click **Enable sandboxes**. See [Sandboxes Getting Started](/sandboxes/getting-started#enable-sandboxes) for the CLI equivalent.
  </Step>

  <Step title="Create a Postgres datastore">
    Navigate to **Add-ons** and create a **Postgres** datastore in the same cluster. See [Datastores](/addons/datastores) for the available configurations. Use one database per QM install.

    You can also bring your own Postgres. QM needs a connection URL that is reachable from inside the cluster.
  </Step>

  <Step title="Create a bucket (optional)">
    Navigate to **Add-ons**, choose **Object storage**, then pick **Create a new bucket** or **Register an existing bucket**. Connect the bucket to the QM cluster.

    The bucket must be in the same AWS account as the cluster and must not be read-only. See [Set up the bucket](/sandboxes/volumes#set-up-the-bucket) for the CLI equivalent.
  </Step>

  <Step title="Create the QM add-on">
    Navigate to **Add-ons** and select **QM**. Pick the cluster, give the add-on a name, then fill in the three steps below and click **Deploy**.
  </Step>
</Steps>

### General

| Setting | Description |
| - | - |
| **Expose QM on a URL** | On by default. Porter provisions a domain for the portal. Sign-in and published apps need it. |
| **Load balancer** | Shown when the cluster has a [private load balancer](#private-load-balancer). **Public LB** is the default. |
| **Database** | Click **Connect existing datastore** to fill in the connection URL from a Porter datastore, or paste a `postgres://` URL. |
| **File storage** | The bucket QM keeps uploads and **Files** data in. |

<Warning>
  Without a bucket, QM keeps files in temporary storage on the core pod. Uploads and **Files** data are lost when QM restarts or updates. Attach a bucket for anything beyond a trial.
</Warning>

### Sign-in

**Password** is the default. Porter fills in your email and generates a password.

<Warning>
  Copy the password before you click **Deploy**. Porter stores only a hash of it, so it can't be shown again. To reset it, enter a new password on the add-on's **Sign-in** tab and click **Deploy**.
</Warning>

See [Sign-in methods](#sign-in-methods) to switch to your identity provider or to email links.

### People

**Administrators** starts with your email. Administrators can invite other people from the QM admin console after first boot.

***

## Sign in to QM

Once the add-on is deployed, open the URL in the add-on header and sign in with the password account.

QM doesn't need a model provider to install. After the first sign-in, set the base model in the QM admin console. The add-on's **Integrations** tab also takes fallback model API keys for agent turns.

***

## Sign-in methods

You can change the sign-in method at any time from the add-on's **Sign-in** tab.

| Method | Description | What you need |
| - | - | - |
| **Password** | One account signs in with an email and password. Use it to get started, then invite others or switch to your identity provider. | A password of at least 12 characters |
| **Your identity provider** | People sign in through an OpenID Connect provider, such as Google Workspace or Okta. | An OAuth client ID and secret from your provider |
| **Email links from QM** | QM emails one-time sign-in links to allowed addresses. | A sender address verified with [Resend](https://resend.com) and a Resend API key |

### Your identity provider

<Steps>
  <Step title="Register an app with your provider">
    Create an OpenID Connect web app with your identity provider. Set its redirect URI to your QM domain followed by `/auth/callback`, for example `https://qm.acme.com/auth/callback`.
  </Step>

  <Step title="Choose the provider">
    On the **Sign-in** tab, select **Your identity provider**, then pick the 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.
  </Step>

  <Step title="Enter the client ID and secret">
    Paste the client ID and secret from the app you registered, then click **Deploy**.
  </Step>
</Steps>

Administrators can always sign in. To let others in, expand 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, the callback URL is missing from your provider's allowed redirect URIs.
</Note>

***

## Private load balancer

You can serve QM from the cluster's [private load balancer](/cloud-accounts/advanced-cluster-settings#private-load-balancer) so it's only reachable from inside your VPC or networks peered to it, for example over [Tailscale](/security-and-compliance/tailscale).

<Steps>
  <Step title="Add the private load balancer to the cluster">
    Follow [Private load balancer](/cloud-accounts/advanced-cluster-settings#private-load-balancer) in the cluster settings, including the DNS provider Porter uses to issue certificates.
  </Step>

  <Step title="Turn on egress enforcement for sandboxes">
    In the **Sandbox** tab, open **Settings** and enable **Enforce egress allowlists** under **Egress controls**.

    Agents run in sandboxes, which can't reach private addresses by default. With enforcement on, Porter lets every sandbox reach the QM domain. See [Reaching QM from sandboxes](#reaching-qm-from-sandboxes).
  </Step>

  <Step title="Select the private load balancer">
    On the add-on's **General** step, select **Private LB** under **Load balancer**. A private QM needs a custom domain, such as `qm.internal.acme.com`.
  </Step>

  <Step title="Create the DNS record">
    The form shows the private load balancer's address and the record type to use. Create that record for the custom domain, then enter the domain and click **Deploy**.

    The private load balancer's address only resolves to something reachable from inside your VPC. Point your own private DNS at it if your clients resolve through one.
  </Step>
</Steps>

To keep published apps private too, don't configure **Public** sandbox networking. See [Published apps](#published-apps).

***

## Published apps

Agents can publish the apps they build. Each published app runs in its own sandbox, and where it's served depends on the cluster's [sandbox networking](/sandboxes/networking):

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

Sandbox networking is optional. To give apps their own hostnames, open **Settings** in the **Sandbox** tab and follow [Configure networking on the cluster](/sandboxes/networking#configure-networking-on-the-cluster) through to the wildcard DNS record.

***

## Reaching QM from sandboxes

Agents run in sandboxes and call back into QM through its URL. Sandboxes can't reach private addresses by default, so a QM on the private load balancer needs **Enforce egress allowlists** turned on in the **Sandbox** tab's **Settings**. With it on, Porter lets every sandbox reach the QM domain.

***

## Updating QM

The add-on's **General** tab has a **Release** picker. Porter installs the newest release on create. You can choose when to move an existing install to a newer one.

***

## 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

<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.
</Warning>


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