Self-host QM

On your computer (pick another name if my-qm is taken):

ssh exe.dev new --name=my-qm
ssh my-qm.exe.xyz

All remaining installation commands run on the VM, as exedev. QM needs about 12 GB of disk; a default VM has room.

Install Node.js and start Docker on boot#

QM's command-line tool needs Node.js 24.15 or later. Docker must start on boot, so QM comes back after a restart:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo systemctl enable --now docker.service
node --version

Expect v24.15 or later.

Create the deployment#

QM keeps a deployment in a folder of its own: settings, secrets, and the skills and tools its agents get. team names your organization inside QM and its containers:

mkdir -p ~/qm && cd ~/qm
npm exec --yes --package=@yc-software/qm@latest -- \
  qm init . --org team --target docker --model-provider anthropic
npm install
npm exec qm -- --version

Expect 0.1.15 or later. npm install pins that version in package.json, so the deployment doesn't change under you.

Point it at exe.dev#

Replace the generated settings. The portal takes port 8000, the one the HTTPS proxy serves at https://<vm>.exe.xyz/, and the model base URLs send Claude and GPT through the LLM integration:

cat > qm.config.jsonc <<EOF
{
  "contract": 1,
  "orgId": "team",
  "publicUrl": "https://$(hostname).exe.xyz",
  "basePort": 7999,
  "target": "docker",
  "modelProvider": "anthropic",
  "model": "claude-sonnet-5-5",
  "services": ["core", "web-ui", "admin", "portal", "auth"],
  "plugins": [],
  "skills": [],
  "env": {
    "auth": { "AUTH_EMAIL_TRANSPORT": "smtp" },
    "core": {
      "HARNESS": "pi",
      "ANTHROPIC_BASE_URL": "https://llm.int.exe.xyz/anthropic",
      "OPENAI_BASE_URL": "https://llm.int.exe.xyz/openai/v1"
    }
  },
  "secretEnv": { "core": { "ADMIN_GRANTS": "ADMIN_GRANTS" } },
  "sandbox": { "backend": "local" }
}
EOF

basePort puts core on 7999, the portal on 8000, the web app on 8001, and the admin console on 8002. Those ports are private too. The local sandbox gives each person a Docker container on this VM as their computer. The email setting is required, but no mail server is set, so QM sends no email; you sign in with one-time links instead.

Add the secrets#

qm init generated most secrets in ~/qm/.env, which only you can read. Add the rest: you as administrator (your exe.dev email, from the reflection integration), placeholder model keys (exe.dev supplies the real credentials outside the VM), core's address for the agent computers, and the sign-in keys:

setenv() { (umask 077; grep -v "^$1=" .env > .env.new || true; printf '%s=%s\n' "$1" "$2" >> .env.new; mv .env.new .env); }
unset_or_empty() { ! grep -q "^$1=." .env; }
ADMIN_EMAIL=$(curl -fsS https://reflection.int.exe.xyz/email | jq -r .email | tr 'A-Z' 'a-z')
setenv ADMIN_GRANTS "$ADMIN_EMAIL:org_admin"
setenv AUTH_ALLOWED_EMAILS "$ADMIN_EMAIL"
setenv ANTHROPIC_API_KEY exe-llm-integration
setenv OPENAI_API_KEY exe-llm-integration
setenv PUBLIC_API_URL http://qm-team-core:8080
for k in AUTH_CLIENT_SECRET AUTH_TOKEN_SECRET PORTAL_SESSION_SECRET; do
  unset_or_empty $k && setenv $k "$(openssl rand -hex 32)"
done
unset_or_empty AUTH_SIGNING_JWK && setenv AUTH_SIGNING_JWK "$(node -e "const {generateKeyPairSync}=require('node:crypto');process.stdout.write(JSON.stringify(generateKeyPairSync('ec',{namedCurve:'P-256'}).privateKey.export({format:'jwk'})))")"
echo "admin: $ADMIN_EMAIL"
npm exec qm -- check

Expect your email and a passing check. It notes that sign-in email is off and points to qm admin-login; that's expected. Teammates you invite later get in by invitation, whatever this allowlist says.

Start QM#

The first start downloads about 4 GB of images and builds the agent computer image, which takes a few minutes:

npm exec qm -- up
curl -fsS http://127.0.0.1:8000/healthz; echo

Expect ✓ stack up — team and {"ok":true}. The containers restart on their own after a reboot.

Let core reach the agent computers#

QM 0.1.15 doesn't tell core which container it runs in, so core can't reach the agent computers, and every command fails with exec daemon never became reachable. The fix is upstream but not released. fix-local-sandbox.sh copies that one-line change into the running core container and restarts it. Run it after every qm up; once a release has the fix, it says so and does nothing:

curl -fsSL -o ~/qm/fix-local-sandbox.sh https://exe.dev/deploy/qm/fix-local-sandbox.sh
chmod +x ~/qm/fix-local-sandbox.sh
~/qm/fix-local-sandbox.sh
~/qm/fix-local-sandbox.sh

Expect qm-team-core patched and restarted (or, on a fixed release, already passes its container name), then already passes its container name the second time.

Set up nightly backups#

backup.sh writes one private archive: the ~/qm folder, the QM tool's state in ~/.config/qm, a database dump, and every agent computer's files. restore.sh puts one back. Lingering keeps the timer running when you're logged out:

curl -fsSL -o ~/qm/backup.sh https://exe.dev/deploy/qm/backup.sh
curl -fsSL -o ~/qm/restore.sh https://exe.dev/deploy/qm/restore.sh
chmod +x ~/qm/backup.sh ~/qm/restore.sh
sudo loginctl enable-linger "$USER"
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/qm-backup.service <<'EOF'
[Unit]
Description=QM backup

[Service]
Type=oneshot
ExecStart=%h/qm/backup.sh team %h/qm %h/backups/qm
EOF
cat > ~/.config/systemd/user/qm-backup.timer <<'EOF'
[Unit]
Description=Nightly QM backup

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now qm-backup.timer
systemctl --user start qm-backup.service
tar -tf "$(ls -t ~/backups/qm/*.tar | head -1)"
systemctl --user list-timers qm-backup.timer

Expect ./qm.dump, ./deployment.tgz, and ./volumes/qm-team-coredata.tgz in the archive, and a scheduled next run.

Sign in#

Print a one-time admin link, good for five minutes:

cd ~/qm && npm exec qm -- admin-login

Open it, click Sign in, and go give it some work.

On the VM, take a fresh backup:

~/qm/backup.sh

To restore on the same VM, pick an archive. QM stops for a few seconds, and everything since that backup is replaced:

~/qm/restore.sh ~/backups/qm/qm-team-YYYYMMDD-HHMMSS.tar
curl -fsS http://127.0.0.1:8000/healthz; echo

Expect restored … and {"ok":true}. Agent computers start again from their restored files the next time someone uses them.

Moving to a new VM? The archive's settings must be in place before QM first starts there, because they hold the database password. On the new VM, install Node.js and Docker, copy the archive over with scp, then:

mkdir -p ~/restore && tar -C ~/restore -xf qm-team-YYYYMMDD-HHMMSS.tar
tar -C ~ -xzf ~/restore/deployment.tgz
cd ~/qm && sed -i "s|https://[a-z0-9-]*\.exe\.xyz|https://$(hostname).exe.xyz|" qm.config.jsonc
npm install && npm exec qm -- up && ./fix-local-sandbox.sh
./restore.sh ~/qm-team-YYYYMMDD-HHMMSS.tar

Then set up the nightly backups again.

On the VM, back up, move to the newest QM, restart with it, and patch core again:

cd ~/qm &&
./backup.sh &&
npm install @yc-software/qm@latest &&
npm exec qm -- --version &&
npm exec qm -- check &&
npm exec qm -- up &&
./fix-local-sandbox.sh

Expect the new version, ✓ stack up — team, and a line from the fix. Check QM's releases first: there is no automatic rollback, so the backup is how you go back.

Ask Shelley, or check on the VM:

cd ~/qm
npm exec qm -- status
npm exec qm -- logs core
docker ps --format '{{.Names}} {{.Status}}'

• exec daemon never became reachable, or the agent says its computer is broken? Run ~/qm/fix-local-sandbox.sh; any qm up undoes it until QM ships the fix. Then ask the agent to try again.
• qm doctor says Anthropic rejected ANTHROPIC_API_KEY? It tests the placeholder against Anthropic directly. Ignore it if chats get replies.
• 401 or a QM sign-in page instead of the chat? Get a fresh link with npm exec qm -- admin-login; each one works once, for five minutes.
• A teammate can't get in? They need both the exe.dev share and a QM invitation, under the same email.
• No model replies? Check ANTHROPIC_BASE_URL in qm.config.jsonc against the settings above, and your LLM integration.
• Nothing after a reboot? sudo systemctl enable --now docker.service; the containers start with Docker.
• Out of disk? df -h /; QM's images take about 8 GB. Grow the disk from your computer with ssh exe.dev resize my-qm --disk=50GB.