Skip to main content
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.
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.

​
Install QM with an AI agent

The Porter MCP server can install and manage QM from an AI agent with the add-on tools. The 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: 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
  • A Postgres database reachable from the cluster
  • Optional: an S3 bucket connected to the cluster
  • Optional: public or private sandbox networking for published apps
Porter rejects a QM install on a cluster without sandboxes, since every agent runs in a sandbox.

​
Setup

1

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 for the CLI equivalent.
2

Create a Postgres datastore

Navigate to Add-ons and create a Postgres datastore in the same cluster. See 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.
3

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 for the CLI equivalent.
4

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.

​
General

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.

​
Sign-in

Password is the default. Porter fills in your email and generates a password.
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.
See 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.

​
Your identity provider

1

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

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

Enter the client ID and secret

Paste the client ID and secret from the app you registered, then click Deploy.
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.
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.

​
Private load balancer

You can serve QM from the cluster’s private load balancer so it’s only reachable from inside your VPC or networks peered to it, for example over Tailscale.
1

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

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

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

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.
To keep published apps private too, don’t configure Public sandbox networking. See 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: Sandbox networking is optional. To give apps their own hostnames, open Settings in the Sandbox tab and follow 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

​
Deleting QM

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.