⚡ Swarm Architecture

Playground Runtime Runbook

📅 Published August 12, 2026 ⏱️ 4 min read 🔬 Peer Verified

# Playground Runtime Runbook

Playground launches evaluations through Matraix Playground batch jobs. The Playground and POST /api/harbor/jobs always use the same artifact layout under jobs/.

Execution planes

| Plane | Meaning | |-------|---------| | harbor (default) | API machine or local dev runs harbor run directly | | remote | API dispatches taskType=harbor_job to a Remote Runner HTTP worker |

Configure the default plane:

`bash export MATRIX_EXECUTION_PLANE=harbor # or remote `

Optional per-request override: "plane": "harbor" or "plane": "remote" on POST /api/harbor/jobs.

Option A: Local Matraix Playground (default)

Terminal A — API

`bash bash application/playground/backend/run_dev.sh `

Terminal B — frontend

`bash cd application/playground/frontend && npm run dev `

Open http://localhost:5173 and launch with Mode → auto.

Option B: Remote Runner worker

Use this when the API should not execute harbor run locally.

Terminal A — Remote Runner

`bash PYTHONPATH=.:environment/runtime:packages/playground/src:application/playground:src \ uvicorn playground.remote_runner.server:app \ --host 127.0.0.1 --port 9100 `

Terminal B — Playground API

`bash export REMOTE_RUNNER_API_URL=http://127.0.0.1:9100 export MATRIX_EXECUTION_PLANE=remote bash application/playground/backend/run_dev.sh `

The worker must have access to the same repository checkout (tasks, personas, jobs/ output directory). Production deployments typically mount a shared jobs/ path or sync artifacts after each run.

Remote Runner API

  • GET /health
  • POST /v1/runs with {"taskType": "harbor_job", "payload": {...}}
  • GET /v1/runs/{id}
  • GET /v1/runs/{id}/artifacts/{name}

Primary payload fields for harbor_job:

  • jobName
  • configYaml — generated Matraix Playground job recipe
  • repoRoot
  • jobsDir
  • env — optional PYTHONPATH plus MATRIX_* task exports only (no API keys)

API keys and other secrets must be configured on the worker process, not sent from the Playground API host.

Optional dev-only taskType=web returns a deterministic mock when REMOTE_RUNNER_WEB_COMMAND is not set.

Environment variables

| Variable | Purpose | |----------|---------| | MATRIX_EXECUTION_PLANE | Default harbor or remote | | REMOTE_RUNNER_API_URL | Remote runner base URL (required for remote) | | REMOTE_RUNNER_API_KEY | Optional bearer token | | REMOTE_RUNNER_INLINE | Run jobs inline in the API process (tests) | | REMOTE_RUNNER_HARBOR_COMMAND | Override harbor CLI command on the worker |

Task types

Matraix Playground resolves execution per task metadata.type:

  • survey / chatbot → host-native agents in auto mode
  • web / os-app → docker or use-computer backends

See [quickstart.md](../quickstart.md) for terminal harbor run examples.