QM Architecture Guide
for Team Deployment

Executive Summary

QM (Quartermaster) is an MIT-licensed multiplayer agent harness that Y Combinator open-sourced on July 31, 2026. Unlike personal assistants, QM is designed for an entire company — every employee and every room gets an isolated agent scope, and people collaborate with the agent through Slack channels, group messages, projects, and a web UI.

YC runs QM internally across accounting, legal, events, and engineering, including using it to build QM itself. The project ships under MIT and is harness-agnostic — Pi, OpenCode, Codex, and Claude Code all drive the same core, so a deployment is not tied to a single model vendor.

Reference Architecture

QM's architecture is deliberately restrained — a small core with pluggable surfaces. Every turn runs through a central headless core, with all substrates hidden behind interfaces so production implementations can be swapped through a single wiring file.

Layer Summary

Core Boundaries and Interfaces

The core itself is generic. Everything specific to one company lives in a deployment directory, and the qm CLI validates and deploys it. Every substrate sits behind an interface:

• Harness — the agent loop driver
• Session store — conversation persistence
• Sandbox — the execution environment
• Memory — scoped context retention

Production implementations are injected through one wiring file, meaning you can replace any substrate without forking core.

HTTP and Plugin Model

The web UI, admin panel, and public portal are optional plugins over the core's HTTP API. Slack is different — it is an optional in-process plugin that the core starts and supervises directly through a service client, using the Bolt framework.

Multi-Tenant Scope Isolation

QM's central design abstraction is the scope. Rather than partitioning by session (like a personal chatbot), QM partitions by person and by space — answering "where should the permission and context boundary sit in the agent era?"

Scope Types

What Each Scope Owns

Every person and every room gets its own scoped instance of:

• Memory — does not leak into another scope
• Files — not mixed with other scopes
• Keychain view — credential visibility is scope-specific
• Permissions — scoped to the person or room
• Crons — scheduled triggers run within the scope
• Web apps — internal apps published to the right people
• Durable sandbox — isolated execution environment

Isolation Properties

The design delivers two key properties simultaneously:

1. Personal isolation — employees customize their own agent without interference. Alice's email token must not appear in Bob's sandbox.
2. Collaborative sharing — in channels and projects, members share context with the same agent.

Collaboration does not require one global memory. Every side effect has attribution through the centralized identity, policy, and audit architecture.

Slack-Integrated Identity

Identity Continuity

The same identity and configuration carries between Slack and the web app. A user who signs in via Slack is the same person in the web UI, with the same scopes, permissions, and keychain view.

Slack as a Plugin

Slack is an optional in-process plugin, not a separate service: the core starts Slack directly, the core supervises Slack, communication uses a direct service client (not HTTP), and it is built on the Bolt framework. This is architecturally distinct from the web UI, admin panel, and public portal, which are optional plugins over the core's HTTP API.

Sign-In Flow

Collaboration Surfaces

The agent can be interacted with in Slack via channels (shared scope for a team), group messages (shared scope for a subset), projects (shared scope for cross-functional work), and DMs (personal scope).

Not documented in public sources: Slack OAuth scopes, event subscriptions, workspace installation steps, signing-secret configuration names, user-to-QM identity mapping fields, whether Enterprise Grid is supported, whether threads or reactions are handled, and the app manifest or token storage design.

Shared vs. Personal Persistent Sandboxes

Each person and each room receives a durable sandbox — an isolated computer where the agent's execute tool runs commands. Installed tools stay installed across sessions, making each sandbox a persistent working environment rather than an ephemeral container.

The execute Tool

The agent has a small, fixed tool surface. The core tool is execute, which runs commands in the scope's own isolated sandbox. This design follows the philosophy that good AI software should be as small as possible — write minimal code, let the model do the rest. Each sandbox contains persistent files, installed tools that persist, and logged-in services (authenticated sessions to external systems).

The sandbox sits behind an interface, and production implementations are swappable through the wiring file. The repository includes sandbox-related directories: aws/microvm-agent (AWS microvm-based sandbox), fly (Fly.io deployment target), local (local test path), deploy (deployment configuration), and scripts (operational scripts).

Security Risks of Durable Sandboxes

Not documented for sandboxes: runtime specification (microvm, container, or VM details), image names, CPU/memory/disk/timeout defaults, lifecycle and persistence-volume implementation, network egress controls, host-to-sandbox mount rules, and Docker image or Compose configuration.

Headless Core — Technical Breakdown

Every turn runs through the central headless core, which handles:

1. API — HTTP interface for all surfaces
2. Identity — authentication and user/scope resolution
3. Policy — security posture enforcement and command policy
4. Scheduler — cron and webhook trigger management
5. Agent loop — the reasoning loop that interfaces with LLM harnesses

Harness-Agnostic Design

The core's key architectural decision is that the harness is behind an interface. Pi, OpenCode, Codex, and Claude Code all drive the same core, and the organization can swap harnesses without replacing the scaffolding around them. This is an explicit anti-lock-in stance — the deployment is not tied to any single model vendor.

Why Headless?

The core is "headless" because the web UI, admin panel, public portal, and Slack are all optional plugins. The core exposes an HTTP API, and any surface can be built on top of it or removed without affecting the core's ability to run agent turns.

Postgres Session and Memory Storage

A central Postgres layer holds all durable state:

Design implications: storage is scope-scoped, so collaboration uses shared room memory rather than a single global context. Execution is durable — scheduled work must survive a browser tab closing, so the queue lives in Postgres, not browser memory. And durable data may persist indefinitely or longer than users expect, so operators must define retention and deletion procedures before onboarding users.

Skill Pack System and Vendor Lock-In Avoidance

Skills are the mechanism by which an organization extends agent capabilities without modifying core. The Skill Pack system has four key properties:

1. Scope-owned — a skill belongs to a person or room
2. Shareable by grant — a scope owner grants a skill to another scope
3. Admin-gated org promotion — promoting a skill to the whole organization requires admin approval
4. Git-imported skill packs — skill packs can be imported from Git repositories

Organization-specific configuration, skills, sandbox image, and infrastructure belong under deploy/layers/. The qm CLI validates this deployment directory. Nothing under deploy/layers/ travels upstream, keeping org-specific customizations private. The repository also ships seed skills (skills-seed/, .codex/skills) and two workflow skills: update-qm (merges upstream QM into a private fork and opens a sync PR) and upstream-pr (sends an org-agnostic fix back to QM upstream).

Vendor Lock-In Avoidance

Security Posture and Governance

An organization selects one security posture. Narrower scopes can only tighten the org-level posture, never loosen it.

A predeclared command policy applies in every posture, including Dangerous: hard denials for commands such as recursive deletes and destructive SQL, plus approval rules for sensitive operations. In Auto mode, a deployment can point the classifier at its own screening proxy to enforce custom content-filtering policies.

Agent Identity Model

QM follows the pattern of local coding agents: the agent acts as the person it works for, it uses that person's credentials and permissions, and everything is audited. Administrators can set organization-level configuration and security posture, select which harnesses and models are available, gate promotion of skills to the whole organization, and control which people receive published internal web apps.

Required External Security Layers

Because QM is not a hardened boundary by default, a robust deployment needs controls at several layers:

1. Identity — external IdP, MFA
2. Scope grants — explicit access lists
3. Sandboxing — strong isolation outside the model
4. Network egress — block unauthorized outbound
5. Data-level authorization — RLS or equivalent
6. Credential lifetime — narrow, short-lived tokens
7. Action approval — human-in-the-loop for sensitive ops
8. Audit — review and retention
9. Emergency shutdown — external operational stop path

Deployment Configuration Checklist

10.1 Baseline Deployment

• Cloud account provisioned (Fly.io or AWS)
• Postgres instance provisioned and accessible
• Node.js runtime available for the core
• Organization slug decided; deployment target chosen (fly or aws)
• Created org-owned deployment repository; added dependency @yc-software/qm
• Ran qm init . --org <slug> --target <fly-or-aws> then npm install
• Followed the generated deployment skill: infrastructure, web sign-in, connector credentials, optional Slack, deployment, live verification
• Sign-in broker configured (built-in email OTP or external IdP)
• Security posture set (Strict recommended for pilot)
• Reviewed SECURITY.md, deployment.md, getting-started.md, and .env.example

10.2 Docker Pilot Hardening

• Docker sandbox image built and pinned to a specific digest; stored in deploy/layers/<org>/
• Container runs as non-root; filesystem read-only, write only to mounted volumes
• CPU and memory limits set; disk quota enforced for persistent volumes
• Network egress restricted (default deny, explicit allowlist)
• No Docker socket mounted; no privileged mode; capabilities dropped (--cap-drop=ALL)
• Sandbox idle timeout and automatic cleanup configured
• Credential injection uses short-lived tokens, not static secrets
• Persistent volumes encrypted at rest; logs shipped to external store
• Separate Docker network per scope where feasible; host machine hardened

10.3 Accounting Workflow

• Security posture: Strict (every tool call requires human approval)
• Scope: personal scope per accountant; shared room for month-end close
• Credentials: read-only API tokens for accounting software (QuickBooks, Xero); no write credentials without per-task approval
• Command policy: hard-deny destructive SQL and recursive deletes
• Data retention and audit: deletion procedure defined; every action on financial data logged
• Cron jobs: inbox triage and report drafting only; no payment authorization
• Prohibited effects: no payments, no production writes, no external customer access
• Human baseline measured on 20–50 comparable tasks; synthetic data first, no live financial data in pilot

10.4 Legal Workflow

• Security posture: Strict; scoped tokens for document management systems only
• Attorney-client privileged material stays in personal scope; legal credentials never shared to rooms
• Auto-mode classifier enabled for external documents; screening proxy for custom legal review rules
• Data retention period defined; every document access and draft logged with attribution
• Command policy: no file deletion or document modification without approval
• Cron jobs: inbox triage and draft preparation only
• Prohibited effects: no filing, no external counsel communication, no contract execution
• Admin membership restricted; review skills before importing untrusted Git skill packs; documented emergency stop path

10.5 Engineering Workflow

• Security posture: Auto for general work; Strict for production deploys
• Scope: personal per engineer; shared room per team/project
• Credentials: scoped GitHub/GitLab tokens (read for repos, PR-only for writes)
• Durable sandbox per engineer with installed tools persisting
• Allowed: run tests, open PRs, monitor CI, check logs. Prohibited: direct production deploys, infrastructure deletion
• Network egress: allow package registries and CI; block unknown hosts
• Skill packs imported from Git; engineering-wide promotion requires admin approval
• Every git operation and CI interaction logged; internal dashboards published to team grant list; external stop path for runaway crons

10.6 Go / No-Go

• Pilot environment deployed separately from production; synthetic or low-sensitivity data used initially
• Cross-scope read isolation tested (attempt and verify failure)
• Indirect prompt injection tested with untrusted inputs; credential misuse path tested
• Duplicate job handling and cancellation tested (can you stop a running agent turn?)
• Emergency shutdown tested; kill-switch, revocation, and rollback expectations tested
• Audit log reviewable and complete; retention and deletion procedures defined and tested
• Admin membership restricted and documented; one workflow with a named owner selected
• Scope boundary documented; human baseline established (20–50 tasks)
• Decision: scale only if completion improves without unacceptable review time, access violations, or unbounded cost

Pilot Deployment Plan

Additional guidance: document every connector secret in the keychain process before switching from Strict to Auto; pair the deployment with material on how AI agents work end-to-end if the operations team is new to tool loops; and review agent skills before importing untrusted skill packs from Git.

Known Gaps and Limitations

QM is early, experimental software with documented limitations. It is explicitly not a hardened public boundary and not a hardened multi-tenant boundary. The following governance expectations require testing before production use: kill switch, revocation, and rollback.

Sources

This guide synthesizes publicly available material on QM as of publication. Primary and secondary sources:

• GitHub — yc-software/qm
• Y Combinator announcement on X
• MarkTechPost — Y Combinator Open-Sources QM
• Wavect — QM AI Agent Review
• explainx.ai — YC Open-Sources QM
• aiweekly.co — YC Open-Sources QM
• b-lab.team — QM architecture analysis

Analysis and deployment framing by Bettroi. QM is an independent open-source project by Y Combinator; Bettroi is not affiliated with Y Combinator. Product and company names are the property of their respective owners.