QM - Porter

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 on the same cluster. To see what teams build with it, read QM use cases.

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. Porter rejects a QM install on a cluster without them.
A Postgres database reachable from the cluster. A Porter datastore works, or bring your own. Use one database per QM install.
Optional: an S3 bucket connected to the cluster, 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, have an AI agent do it with the Porter MCP server, or set up the prerequisites with the Porter CLI.

From the dashboard

Open QM

In the Porter dashboard, go to Agents and click Deploy QM.

Pick a cluster, name it, and set up storage

Choose the cluster and enter a name: lowercase letters, numbers, and -, up to 31 characters. Then fill in General:

Setting	What to do
Expose QM on a URL	Leave it on. Porter gives the portal a domain with TLS. Sign-in and published apps need it.
Load balancer	Only shown if the cluster has a private load balancer. Public LB is the default.
Database	Click Connect existing datastore to fill in the URL from a Porter datastore, or paste a `postgres://user:password@host:5432/qm` URL.
File storage	Pick the bucket for uploads, snapshots, and Files data.

Without a bucket, QM keeps files in temporary storage, and they’re lost whenever QM restarts or updates. Attach a bucket for anything beyond a trial.

Create datastore and Create bucket leave the form and discard your changes. Create them before you start.

Choose how people sign in

Password is the quickest way to start. Porter fills in your email and generates a password. You can switch to another sign-in method at any time.

QM sign-in settings with a password account

Copy the password before you click Deploy. Porter stores only a hash of it, so it can’t be shown again.

Once QM is deployed, open the URL in the add-on’s header and sign in with this account. The URL is your custom domain if you set one, otherwise the Porter domain.QM doesn’t need a model provider to install. After your first sign-in, set the base model in the QM admin console. The add-on’s Integrations tab also takes fallback API keys for Anthropic, OpenAI, and OpenRouter, plus Slack bot credentials.

Add administrators and deploy

Administrators can manage QM and can always sign in. Your email is added for you. Invite everyone else from the QM admin console after first boot.

Click Deploy.

With the Porter MCP server

The Porter MCP server lets an AI agent such as Claude Code or Cursor install and manage QM for you.

Install the Porter MCP server and skills

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.

Ask your agent to set up QM

For example:

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.

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.

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 or with the MCP server.

Select the cluster

porter config set-cluster <CLUSTER_ID>

Enable sandboxes

porter sandbox enable --wait

Create a Postgres datastore

Add a Postgres add-on to a porter.yaml and apply it. See Add-ons in porter.yaml for the options.

porter.yaml

addons:
  - name: qm-db
    type: postgres
    kind: in-cluster
    config:
      storageGigabytes: 10
      cpuCores: 0.5
      ramMegabytes: 1024

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.

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 and a Resend API key

Use your identity 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.

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.

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.

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 to make it reachable only from your VPC or networks peered to it, for example over Tailscale.

Add the private load balancer to the cluster

Follow Private load balancer in the cluster settings, including the DNS provider Porter uses to issue certificates.

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.

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:

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

​Prerequisites

​Deploy QM

​From the dashboard

​With the Porter MCP server

​With the Porter CLI

​Sign-in methods

​Use your identity provider

​Private load balancer

​Published apps

​Manage and update QM

​Troubleshooting

​Deleting QM

Prerequisites

Deploy QM

From the dashboard

With the Porter MCP server

With the Porter CLI

Sign-in methods

Use your identity provider

Private load balancer

Published apps

Manage and update QM

Troubleshooting

Deleting QM