Skip to content

English · 日本語

Self-hosting the web UI

The self-hosting roadmap (BE-0016) covers running the bajutsu web UI (cli) on hardware you own, reachable by your team over a private Tailscale network. Two tiers are available today, both made safe to expose by BE-0051's auth + input validation:

  • Tier A — a single Mac. A token-authenticated bajutsu serve and a local bajutsu worker that runs its jobs, both on one Mac. The rest of this page up to Tier B covers it.
  • Tier B — a self-hosted server backend. BE-0015's control plane (FastAPI + Postgres + S3-compatible storage + GitHub OAuth + RBAC + quotas) on a Linux node, with Mac workers. It runs single-tenant by default and supports multiple orgs when you declare them in config (see Tier B — self-hosting the server backend).

The fully managed public cloud offering (a hosted MacStadium worker pool + IaC) remains future (BE-0015).

The macOS constraint

The runner drives an iOS Simulator, which needs a GUI login session (the Aqua session) — it will not run from a headless daemon. Every choice below follows from that:

  • Run serve as a per-user LaunchAgent (GUI session), not a LaunchDaemon.
  • Auto-login the Mac so a GUI session is recovered after a reboot (FileVault needs one interactive login after a cold boot before auto-login proceeds).
  • Disable sleep so the session stays alive: sudo pmset -a sleep 0 disablesleep 1.

These constraints are specific to the iOS Simulator (XCUITest) backend. The web (Playwright) backend runs a headless browser and needs none of them — it can serve from any Mac or Linux host (including the Tier B node), so a web-only deployment skips this section.

1. Generate the LaunchAgent

First install the backend's runtime dependencies into the venv the agent will use. The agent runs python -m bajutsu serve directly, so — unlike make serve — it does not install them on demand. Install the backend's runtime closure — the single extra that names everything a run reaches, including the visual (screenshot) and schema (responseSchema) assertion deps (BE-0173): for the web (Playwright) backend, uv sync --extra worker-web && playwright install chromium; for the iOS Simulator (XCUITest) backend, uv sync --extra worker-ios (the XCUITest backend needs no backend pip extra — Xcode supplies xcodebuild, and the target supplies its prebuilt driver.runner.testRunner — so worker-ios is just the visual + schema assertion deps). Installing a bare backend extra (e.g. web) under-installs — such a run fails lazily at assertion time — and skipping the closure entirely makes runs fail at dispatch with no available actuator.

bajutsu serve --emit-launchagent prints a launchd plist matching the serve flags you pass, then exits without starting a server. Pick a strong token and write the plist into your LaunchAgents:

export TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
bajutsu serve --emit-launchagent --config bajutsu.config.yaml --token "$TOKEN" \
  > ~/Library/LaunchAgents/com.bajutsu.serve.plist
chmod 600 ~/Library/LaunchAgents/com.bajutsu.serve.plist   # the plist holds the token

The emitted plist:

  • runs python -m bajutsu serve --host 127.0.0.1 --port 8765 --config … (the same interpreter you ran the command with, so it uses your venv) with RunAtLoad + KeepAlive;
  • puts the token in EnvironmentVariables (BAJUTSU_SERVE_TOKEN) — never in the argv, so it isn't visible in ps;
  • writes stdout/stderr to ~/Library/Logs/bajutsu-serve.{out,err}.log.

Two settings the emitted plist leaves out, both added under EnvironmentVariables:

  • ANTHROPIC_API_KEY — needed for the AI paths (record, --system-alert-handling); it isn't baked in for you. (For the Bedrock provider, set BAJUTSU_AI_PROVIDER / BAJUTSU_BEDROCK_MODEL and the AWS credentials here instead.)
  • PATH — for the iOS (XCUITest) backend only. launchd starts the agent with a minimal PATH, and bajutsu locates xcodebuild / xcrun / simctl through PATH, so without it a run fails with no available actuator. Include the Xcode command-line tools' bin, Homebrew's bin, and the venv's bin. (The web backend finds Playwright by import, not PATH, so it needs no PATH entry.)

PlistBuddy makes both edits without hand-editing XML (run from the repo root so .venv resolves):

PLIST=~/Library/LaunchAgents/com.bajutsu.serve.plist
/usr/libexec/PlistBuddy -c "Add :EnvironmentVariables:ANTHROPIC_API_KEY string sk-ant-…" "$PLIST"
/usr/libexec/PlistBuddy -c "Add :EnvironmentVariables:PATH string $(brew --prefix)/bin:/usr/bin:/bin:/usr/sbin:/sbin:$(pwd)/.venv/bin" "$PLIST"

The agent starts the server alone. The server queues every job for a bajutsu worker and runs none itself (BE-0449). Run a worker beside it as a second LaunchAgent:

  1. Copy the plist under another label.
  2. Change its ProgramArguments to python -m bajutsu worker --platform ios. Append --server-state-dir <project>/.bajutsu, where <project> holds the server's runs directory. --server-state-dir lets the worker take the jobs that name files on this machine. See the server backend on one machine. Add --server-url http://127.0.0.1:<port> when the server listens on a port other than 8765.
  3. Put the same token in its EnvironmentVariables, as BAJUTSU_TOKEN.
  4. Leave the working directory unchanged. The worker runs each job in a temporary directory. Pass --workdir <dir> to keep that workspace in one fixed place.

Until a worker polls, every job stays queued, and the UI says that no worker is available.

serve stays bound to 127.0.0.1; the next step is what makes it reachable.

2. Load it

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.bajutsu.serve.plist
launchctl print gui/$(id -u)/com.bajutsu.serve        # verify it's loaded

To reload after editing the plist: launchctl bootout gui/$(id -u)/com.bajutsu.serve then bootstrap again.

serve stays on 127.0.0.1; Tailscale publishes it inside your tailnet only — identity-based access plus automatic TLS, no public surface:

tailscale serve --bg 8765    # → https://<machine>.<tailnet>.ts.net (reachable only in the tailnet)

Teammates open that URL; the UI prompts for the token on first load (the browser then carries a session cookie). API clients send Authorization: Bearer $TOKEN.

Do not bind 0.0.0.0 to the public internet. Even with a token, the safe default is a private tailnet. serve refuses a non-loopback --host without a token, but a public bind widens the surface needlessly. If you need a real internal hostname, front serve with Caddy for TLS (+ basic auth) and keep it off the open internet.

Security recap (BE-0051)

A self-hosted serve relies on the hardening from BE-0051: token auth on every request, /api/run and /api/record confined to the app's scenarios dir with validated backend/udid, a CSRF Origin check plus security headers, and a concurrency cap on run dispatch. Keep the token secret, keep the Mac on a tailnet, and keep the OS patched.

The CSRF/Origin check and a Host-header allowlist run unconditionally (BE-0121) — not only when a token is set. Running these checks unconditionally matters most for the common make serve default (loopback, no token): a cross-origin POST from a page open in another tab is blocked, and a request whose Host does not name a bound interface is refused, so a rebound hostname can't reach a loopback endpoint such as GET /api/apikey. A non-browser client (no Origin header) is unaffected. The Host allowlist is derived from the interface serve binds — the loopback names for a loopback bind, that host otherwise; a wildcard bind (0.0.0.0 / ::), whose reachable names can't be enumerated, disables the Host check and leaves CSRF as the cross-origin guard.

Uploaded-config command execution (BE-0090)

An uploaded .zip bundle can carry a config whose services.server.cmd (and, once wired, services.mockServer.cmd) names a shell command to bring up the app under test. That command is untrusted input, so serve never runs it on the bare host. The --upload-exec option (or the BAJUTSU_UPLOAD_EXEC environment variable, for the hosted backend) chooses what happens when an uploaded bundle's run needs that command — it applies only to upload-sourced configs; a local or Git-sourced config is operator-trusted and unaffected:

  • sandbox (the default) — run the command inside a throwaway Docker container, never on the serve host. The bundle declares its runtime with exactly one of dockerImage (a published base image, e.g. node:20-slim) or dockerfile (a bundle-relative path that serve builds with docker build), plus a port (the in-container listen port). The container is hardened — --rm, all capabilities dropped, no new privileges, a read-only root filesystem with a tmpfs scratch, a non-root user, CPU/memory/pid caps, and only its one port published to a loopback host port — and torn down after the run. Docker must be installed on the serve host.
  • reuse — never run the uploaded command; only probe an operator-provisioned server already answering at subject.url. If nothing answers, the run fails loud rather than starting anything.
  • deny — refuse the uploaded command outright; like reuse, an externally-answering server is accepted, otherwise the run fails loud.

No mode ever runs an uploaded command on the bare host, and none silently falls back to doing so — a blocked or misconfigured services.server fails with a clear error, never a flaky-looking run. The decision (denied / reused / sandboxed, and the image when sandboxed) is recorded in the run's manifest.json provenance, so "what did this run execute, and what was suppressed?" stays answerable.

Remote-config command execution (BE-0121)

A config bound at startup with --config (a local path or a github: spec you typed yourself) is operator-trusted: serve runs its subject.build command normally. A Git config bound later, through the UI's "from Git" picker (POST /api/config with a git spec), is a different trust level — a cross-origin request could have bound it — so it is treated like an uploaded bundle: its subject.build command is never run on the host by default. Pass --allow-remote-build (or set BAJUTSU_ALLOW_REMOTE_BUILD=1) to opt in when you deliberately drive runs off a UI-bound Git config whose build you trust. Without the opt-in the run proceeds with the build suppressed, exactly as an uploaded bundle's build is suppressed — no silent host-side command execution from a config that arrived over the network.

The same verdict covers the XCUITest runner's on-demand build, driver.runner.build. serve does not run that command itself; the run it spawns would, when the file at driver.runner.testRunner is missing. For an uploaded bundle, or a UI-bound Git config without --allow-remote-build, the spawned run refuses that build and fails with driver.runner.build withheld instead. Such a config ships its .xctestrun prebuilt at testRunner, which the run then uses as is.

Private-repository access for the Git config source (BE-0224)

When serve (or the CLI) reads its config from a private GitHub repository — a github: spec, BE-0063 — it needs a credential that grants read access. A public repository needs none. The credential is resolved per fetch in this order (so rotating it takes effect without a restart):

  1. a configured GitHub App installation (recommended for an unattended host — see below);
  2. a credential entered via the web UI's "From a Git repository" dialog (held in BAJUTSU_GIT_CONFIG_TOKEN — see below);
  3. GITHUB_TOKEN / GH_TOKEN from the environment;
  4. gh auth token, for a developer with an interactive gh session on their own machine;
  5. otherwise anonymous (public repositories only).

Grant least privilege. A classic personal access token (PAT) with the repo scope grants read/write to every private repository the person can see — far more than "read one test repo". Prefer a fine-grained PAT (or a GitHub App installation) scoped to only the target repositories with the single Contents: read permission.

Supplying a token to an unattended daemon

A launchd / systemd serve has no interactive gh session, so inject the token at the daemon level. For the LaunchAgent in step 1, add it to the plist's EnvironmentVariables; on Linux/systemd use the unit's Environment= (or an EnvironmentFile= that is not world-readable). A PAT is tied to a person, though: it carries that person's access and stops working when they rotate it or leave. A service that reads private repos unattended should authenticate as itself — a GitHub App.

A GitHub App installation token is short-lived, limited to the installation's repositories, and tied to the service rather than a person. Create an App with Contents: read, install it on the target repositories, then supply:

export BAJUTSU_GITHUB_APP_ID=123456
export BAJUTSU_GITHUB_APP_PRIVATE_KEY_FILE=/etc/bajutsu/app.pem   # or BAJUTSU_GITHUB_APP_PRIVATE_KEY inline
# optional: pin the installation; otherwise it is resolved from the repository being fetched
export BAJUTSU_GITHUB_APP_INSTALLATION_ID=7654321

The App path signs a short-lived RS256 JSON Web Token (JWT) with the private key and exchanges it for an installation token. It uses cryptography, installed on demand with the githubapp extra (uv sync --extra githubapp); a deployment that authenticates with a PAT never loads it.

Because the App credentials come from the process environment, a configured App applies to every request and takes precedence over any PAT — including one entered in the web UI, and, on a hosted multi-organization deployment, over every organization's own stored credential. Configure one or the other, not both, unless you intend the App identity to authenticate all fetches.

Entering a credential from the web UI

The "Open config" dialog's "From a Git repository" source has a credential field. Enter a fine-grained PAT or App token and it is stored write-once through serve's secret store — the same store as the Claude API key: masked, never echoed back. On a local serve it is held for the lifetime of the process in a bajutsu-owned variable (BAJUTSU_GIT_CONFIG_TOKEN) that the fetch reads ahead of an ambient GITHUB_TOKEN — deliberately not GITHUB_TOKEN itself, so entering or clearing a UI credential never disturbs a token you exported at launch. A server with a database encrypts it at rest and scopes it per organization. Each tenant's stored credential is its own. A local start and the hosted backend both have such a database. The bind hands the organization's stored value to its own fetch (BE-0449). That value ranks after a configured GitHub App and ahead of an ambient token. It reaches the fetch and never a response. When a bind fails for lack of access, the dialog shows the diagnostic inline — the message names the real cause (a rate limit, an organization single sign-on (SSO) authorization gap, a rejected token, or "provide a credential with Contents: read for <owner>/<repo>") rather than a bare 404.

Tier B — self-hosting the server backend

Tier A is a server and its local worker on one Mac. Tier B runs BE-0015's server backend — the FastAPI control plane with Postgres, S3-compatible storage (MinIO), GitHub OAuth, RBAC, and a per-user quota — on a Linux node, with one or more Macs as workers. It runs single-tenant by default (every user in one default org) and supports multiple orgs once you declare them in config — see Multiple orgs below. The ready-to-run stack is in deploy/self-host/ (compose + Dockerfile + .env.example).

Tier B topology diagram: team laptops reach the Linux control-plane node (bajutsu serve --asgi, Postgres, MinIO) over HTTPS via Tailscale or Caddy; the control plane dispatches jobs over HTTP to a pool of bare-metal Mac iOS (XCUITest) workers and, over the same Tailscale tailnet, to containerized Linux web (Playwright/Chromium) workers, both returning results to the control plane.

Mermaid source
flowchart TB
    laptops(["team laptops"])
    control["Linux node — docker compose<br/>bajutsu serve --asgi<br/>postgres · minio<br/>[+ Linux web worker container(s)]"]
    macWorker["Mac worker × N (bare)<br/>bajutsu worker (iOS · XCUITest)<br/>bajutsu run · Simulator"]
    webWorker["Linux web worker (web)<br/>bajutsu worker · Chromium"]

    laptops -->|"HTTPS (Tailscale tailnet,<br/>or Caddy at a hostname)"| control
    control -->|"jobs (HTTP)"| macWorker
    macWorker -->|result| control
    control -->|"jobs (Tailscale tailnet)"| webWorker
    webWorker -->|result| control

The Linux control plane is cheap; the Mac workers carry the Simulator runs and are the scarce part. The fleet is heterogeneous by backend: a Mac iOS worker runs bare metal because it needs the Aqua GUI session for the iOS Simulator (exactly like Tier A), while a Linux web (Playwright) worker runs headless in a container (BE-0173) — the web backend has no GUI-session constraint. Both lease from the same control plane over HTTP; the web-worker container needs no cloud SDK or object-store secrets (BE-0160), only the control-plane URL and a token. Running a mixed fleet is optional — an iOS-only deploy is the default and unchanged; add web workers when you host web runs (§ Add a Linux web worker).

Config sources are deployment-aware (BE-0108). The "Open config" dialog binds the active config from up to three sources: a Git repository, an uploaded .zip bundle, and a file browser over the serve host's --root. On the server backend (this tier) the file browser is dropped — both hidden in the UI and refused server-side (/api/fs and the path branch of POST /api/config return 403) — leaving only Git and upload. A hosted user has no filesystem relationship to the shared worker, so browsing the operator's --root could bind nothing they own; removing it also avoids handing every logged-in user a directory listing of that tree. A local start (Tier A, a self-hosted single Mac) keeps all three: there the filesystem is the operator's own.

Local vs. hosted, across config, scenario, and the app binary

The walkthrough above is organized by how you deploy; this box collects what changes for each kind of state serve manages, so the tier-by-tier detail is easier to place. "Local" below covers both Tier A and a bare make serve on a laptop. Both run with hosted: false. Tier B's server backend names a bucket in BAJUTSU_SERVER_STORE, which makes it hosted: true. A server backend on one machine with no bucket stays hosted: false. The section The server backend on one machine, below, covers that case.

State Local (hosted: false — Tier A, or a bare make serve) Hosted (hosted: true — Tier B server backend)
Config File browser + Git + upload; own filesystem, paths unconfined Git + upload only; file browser disabled, 403 (BE-0108)
Scenario and run artifacts scenarios/ and runs/ on disk, with the queue and the run history in .bajutsu/queue.db; soft-delete leaves a .deleted marker in the run tree Object store (S3/GCS) + Postgres; soft-delete sets deleted_at (BE-0239)
App binary subject.path on disk; build only when missing — never for an uploaded bundle, which ships its binary prebuilt An uploaded bundle's binary ships to the worker via presigned URLs, no build runs (BE-0413); a Git-sourced config still has the worker build from the checkout, remote build gated (BE-0121)
Authoring against a live screen Capture mode and Edit's live picker both hold a driver open in the serve process Neither is offered: both controls are disabled, each carrying the reason (#1721)
  • Config. Both sides bind from up to three sources, but the file browser disappears the moment hosted is true (just above). Path confinement follows the source, not the tier: a local-file config resolves against its own directory and is unconfined (it may point at a sibling), while a Git- or upload-sourced config is untrusted and its paths.scenarios / paths.baselines / subject.path are confined to the checkout or bundle root regardless of which tier bound it (configuration.md → Config from a Git repository). Hosted mode never offers the local-file source, so every hosted config ends up confined — a side effect of dropping the file browser, not a separate rule.
  • Scenario and run artifacts. Locally, the scenario store and the run history read and write a plain directory tree (scenarios/, runs/); a soft-deleted run keeps its tree and gains a .deleted marker. Hosted, both live in the control plane's object store (BAJUTSU_SERVER_STORE, S3-compatible or GCS) plus a Postgres row per run, so a soft-delete sets deleted_at instead of moving bytes on disk (see Deleting runs, and how long the trash is kept, below).
  • Authoring against a live screen. Capture mode records a scenario by clicking on a screenshot. The Edit mode's live picker resolves a selector against the screen the device is showing. Both hold a driver open inside the serve process itself, for as long as the author keeps clicking. Hosted, the devices sit on the workers, which the browser never talks to, so every /api/capture/* route is local-only and a hosted deployment answers 404. The boot read (GET /api/config) reports the absence as a capability flag. A hosted Author tab then disables both controls — each showing the server's own reason — and opens in Edit mode, rather than offering a mode whose first call fails (#1721). A deployment that is not hosted serves the capture routes on either transport: a local bajutsu serve --asgi and a local start of the server backend both keep Capture, since the devices are on the machine (BE-0449). The Record tab keeps working: POST /api/record dispatches a job the way a run does, so a recording made through the AI path still runs hosted.
  • App binary. An uploaded bundle already carries a prebuilt binary, so its subject.build never runs regardless of tier (_governed_build, DESIGN §1 "Bajutsu does not build the app"). Hosted, the worker still needs the bytes: the job lease response's bundle_urls field carries one presigned GET URL per stored object the bundle is made of, and the worker fetches them over plain HTTP and reassembles its own workspace before the run starts (BE-0413) — no shared filesystem, and no build. A Git-sourced (or, locally, file-browser-sourced) config instead resolves subject.path from the bound config and, if it's missing, runs the config's subject.build command; hosted, a Mac worker builds from the same checkout materials the control plane resolved for the job, exchanging bytes over presigned URLs rather than a shared filesystem (BE-0160, above). The remote-build gate is orthogonal to the tier: any config bound later through the UI's "from Git" picker has its subject.build suppressed by default, whether the UI sits on a laptop's Tier A or Tier B's control plane — only a config supplied at startup is operator-trusted (see Remote-config command execution, above). The web (Playwright) backend has no binary concept on either side; the browser engine installs on demand instead.

The server backend on one machine (BE-0449)

bajutsu serve starts on one machine with no cloud service and needs no environment variables there. The server runs no job itself. It queues each kind of job for a worker:

  • a run, with its build phase
  • a run-set, the fan-out of a target's scenarios
  • a triage, a record, or a crawl

A bajutsu worker on the same machine leases each job and runs it. make serve starts that worker for you. Without a worker, a job stays queued, and the UI says that no worker is available.

A job that names its files by paths on the server's disk goes to a worker on that machine alone. A local start keeps a random machine identity in .bajutsu/machine-id, beside the runs directory. A run, triage, record, or crawl can name its config and runs directory by those paths. Such a job requires the capability token machine:<id>. A worker advertises the token when it starts with --machine-id <id>. It can read the identity instead, with --server-state-dir <dir>. make serve passes --server-state-dir to the worker it starts. A worker on another machine never leases such a job, nor does a Device Farm worker. The UI keeps saying that no worker is available until a worker on the server's machine polls. A job that ships its files, such as a run off an uploaded bundle, requires no machine token and goes to any worker. A worker that holds the identity but lacks the server's files still fails the job. The worker reports that the job needs a worker on the server's machine.

We deprecate the --backend flag. The flag once chose between two backends. The local backend ran jobs inside the server process, and the server backend queued them. Both values now start the same server, so the flag changes nothing. bajutsu serve still accepts either value and prints a warning. The next release removes the flag. Drop it from a command line, a LaunchAgent, or a container command. An unknown value still stops the start.

A triage job reads the run it diagnoses from the server's runs directory. Its command line names the run directory by its absolute path on the server's disk. The bound config and the scenario source get absolute paths too. The job writes triage.json into the run directory, and the UI reads the file from there. A worker on the same machine runs the job from the config's directory, as it runs a local run. Like a run, the job goes to a worker on the server's machine alone. A triage with --ai reads the AI key from the lease, like every queued job. A key set in the UI thus reaches the investigator and never enters the job spec.

A crawl or record job also needs a worker on the server's machine. A crawl writes its screen map into the server's runs directory. A record writes its scenario into the target's scenarios directory. While a crawl runs, its worker posts each new screen map to POST /api/worker/artifact. The server relays each snapshot to the Crawl tab as an artifact event on the job's event stream. The graph thus grows as the worker explores. The file stays the durable copy, and the page reads it once the job ends. The worker skips a snapshot over 2 MiB. A job has a live budget of 16 MiB. Past it, the stream says so once, and the page reads the file instead. A worker on another machine leaves no file on the server's disk while the crawl runs. There, the graph updates once the job ends.

A record can pause and ask the person at the browser for help, such as a one-time password. Its worker posts the request to POST /api/worker/handoff, and the page shows it as before. The server encrypts the answer under the secrets key and keeps it in the jobs table. While the record waits, its worker polls POST /api/worker/handoff-response once a second. The worker takes the answer from there and writes it to the record's standard input. The answer leaves the table when the worker reads it, or when the job ends. The server drops an answer older than the record's five-minute wait. A cancel reaches a waiting record through the same poll, before any heartbeat.

Three rules guard the relay routes:

  • Each route accepts a post from the lease holder alone. Any other worker gets 409. The handoff route also takes a record job alone, and one request at a time. A job's requests stay within 64 MiB.
  • A caller on a browser or machine login gets 403. The shared token a worker holds is the one credential these routes accept.
  • An answer to a handoff is an editor action in the job's own org, checked like a cancel.

For each setting left unset, the server supplies a local default. Every default lives in a .bajutsu/ directory beside the runs directory. The server creates that directory owner-only (0700), and Git ignores it. These defaults apply when BAJUTSU_SERVER_STORE is unset. A deployment with a bucket gets no default database. A SQLite file per replica would split the queue across the replicas. Such a deployment must set BAJUTSU_DATABASE_URL, or the server refuses to start. The server runs no job itself, so a server with no queue could run nothing.

A plain pip install bajutsu is enough for this shape. The base dependencies carry the server stack, such as FastAPI, SQLAlchemy, and cryptography. SQLite ships with Python. The server extra adds boto3 for an S3 bucket, and the db extra adds psycopg for PostgreSQL. A hosted deployment still installs those extras, as the Tier B image does.

Setting left unset Local default
BAJUTSU_DATABASE_URL A SQLite file, .bajutsu/queue.db. The server migrates it to the latest schema at every start, because no operator runs Alembic for it.
BAJUTSU_SECRETS_KEY A Fernet key generated once into .bajutsu/secrets.key, an owner-only (0600) regular file. Applies to the default SQLite alone. A configured BAJUTSU_SECRETS_KEY takes precedence.
BAJUTSU_SERVER_STORE A file:// store, served by the server's own /api/store/objects/ routes. The default org's runs stay in the runs tree; every other object lives in .bajutsu/objects/.
BAJUTSU_HOSTED false. With a bucket named, true.

A configured database keeps the earlier rule. With BAJUTSU_DATABASE_URL set and no BAJUTSU_SECRETS_KEY, the server refuses to start. The server never generates a key for an operator's own database. Startup also refuses an unsafe key file that already exists. A symlink, a file another account owns, or a file open to group or other counts as unsafe. On a shared host, a key that another local account can read would expose every stored secret.

One .bajutsu/ serves one server at a time. The server holds a lock on .bajutsu/serve.lock while it runs. A second bajutsu serve on the same directory refuses to start and names the directory. Two servers there would share one queue: each would hand out job ids the other already used, and a worker of either would take the other's jobs. To run two servers from one checkout, point each one's --runs at a directory under its own parent, since .bajutsu/ sits beside the runs directory. Or give each its own BAJUTSU_DATABASE_URL and BAJUTSU_SECRETS_KEY. The lock ends with the process, so a server that crashed leaves nothing to remove.

The file store uses the bucket's key layout, with one difference. The default org's run artifacts have keys under artifacts/<run id>/. They stay where bajutsu run writes them, at runs/<run id>/. A run from the command line resolves through the store without moving a file. The same holds for a run already under runs/. Every other object lives in .bajutsu/objects/ under its bucket key. Uploaded bundles and every other org's runs, scenarios, and baselines go there. The default org's scenarios and baselines stay on the local tree, as the next subsection describes. Keeping the other objects out of runs/ keeps tenants apart. A default-org request for a run named acme or scenarios finds nothing. It can neither read nor delete another org's runs or a store folder.

The server leaves the runs directory itself as it is. It creates runs/ when it is missing, but never changes its mode. A symlinked runs/, such as one moved to a larger disk, is followed. Every key is confined to the resolved directory, so none reaches outside it. Only .bajutsu/objects/, which the server owns, is made owner-only (0700), and a symlink there is refused.

The server and the command line share the runs tree. A run deleted through the server stays at runs/<run id>/ with a .deleted marker. Both bajutsu flakiness --history and bajutsu triage --flaky skip a tree that holds the marker. The run thus stays deleted for the command line as well.

The browser and the worker reach a stored file through a signed URL. The server signs each URL with an HMAC key. That key lives in .bajutsu/store-signing.key, under the same 0600 rules. Each URL names the --host the server was given, or 127.0.0.1 for a wildcard bind. The FastAPI transport alone serves these routes. A server without a bucket switches itself to --asgi and says so at startup. The URLs carry the port fixed at startup, and such a server refuses --port 0.

The run history comes from the runs table and not from the directory listing. At startup the server indexes every run tree under runs/ into the runs table, under the default org. The index skips a tree with no readable manifest.json. It also skips a run that a job is still writing. The index never updates a row. A run the table already holds keeps the row its job wrote. A run that bajutsu run writes while the server is up needs a rescan. An admin calls POST /api/runs/rescan, which indexes the new trees and returns {"indexed": <count>}. A deployment with a bucket answers the rescan with 409, since its runs do not live under runs/.

hosted is a deployment setting of its own, read from BAJUTSU_HOSTED. The variable accepts true, false, 1, or 0. Any other value stops the start with an error. When the variable is unset, hosted follows the store. A bucket in BAJUTSU_SERVER_STORE makes it true, so an existing Tier B deployment behaves as before. Otherwise hosted is false. A database does not imply hosted. A local start with a queue keeps the file browser (BE-0108). It also keeps the device takeover of record (BE-0185), since the author sits at the device.

What a local start keeps from the earlier local backend

A local start keeps the features of the earlier local backend. That backend ran jobs inside the server process. Each item applies to the default org of a local start. That org is the one whose runs already live in the runs tree.

Feature Where a local start keeps it
Capture mode and the live step picker of the editor The FastAPI app serves /api/capture/* and /api/ant/login on any deployment that is not hosted. The UI offers Capture as on the local backend.
Secrets set in the UI The database keeps them encrypted. A job receives them in the worker's lease, so it gets the AI key and every ${secrets.X} value in its environment.
Scenarios Saved to the scenarios directory of the bound config, the same directory the scenario list reads.
Visual baselines Approved into the --baselines directory, the one a run is pointed at. The file store mounts that directory at baselines/, so a worker downloads the same files. The start refuses a --baselines directory that holds the runs directory or .bajutsu/.
AI provider settings Read from and written to provider-settings.json beside the runs directory, the file the earlier local backend used (BE-0184).
A run's files A run names the bound config, its scenario, the runs directory, and the --baselines directory by their paths on this machine. The worker on the same machine builds and runs it from the config's directory, and writes the run tree straight into runs/.

The server reads a stored secret in plaintext on two paths. No HTTP response carries the value (BE-0136).

Path What the value is for
A worker leases a job The lease response, which the worker receives
The server binds a config from a private Git repository That fetch's credential

The lease relays the secrets of the leased job's org and no other. A caller that authenticates with the shared token receives them. On a loopback start with no token, any caller does. A browser or machine login that reaches the lease route gets none. The values never enter the job spec. The queue's database thus keeps them in their encrypted rows alone. A worker lays them over the job's environment, never its argv. The job's environment leaves out the Git credential, because a job never fetches a config.

A secret may not set a variable that changes how a job's processes load or run. The server and the worker both drop such a name and log it, without its value:

Denied Names
Shell and system variables PATH, HOME, USER, SHELL, LANG, TERM, PWD, OLDPWD, LOGNAME, TMPDIR, DISPLAY, IFS, ENV, BASH_ENV, PS4, PROMPT_COMMAND
Interpreter options NODE_OPTIONS, NODE_PATH, RUBYOPT, RUBYLIB, PERL5OPT, PERL5LIB, JAVA_TOOL_OPTIONS, _JAVA_OPTIONS
Name prefixes LD_, DYLD_, PYTHON, BAJUTSU_

On macOS and Linux the deny list matches a name in its exact case; on Windows, case does not matter. The same rule applies to a config's ai.keyEnv and its evidence.secrets names. A denied ai.keyEnv makes the server read ANTHROPIC_API_KEY and log a warning.

A run that waits for a worker says why. The wait ends once a live worker advertises every capability the run requires. Until then, three places show a notice that no worker is available:

  • the notice field of the job view, GET /api/jobs/<id>;
  • a notice event on the job's live stream, /api/jobs/<id>/events;
  • the run's status line in the UI.

A worker counts as live when it polled or sent a heartbeat within the lease timeout. The bajutsu_unroutable_jobs metric uses the same window. The notice clears as soon as such a worker polls, or a worker leases the run.

The provider settings stay in the file rather than moving into the database. A local start then reads and writes the copy the earlier local backend wrote. A user who upgrades sees the same choice.

Another org on a local start keeps the bucket layout under .bajutsu/objects/. Its scenarios and baselines reach the worker the way they do on a hosted deployment. No tenant writes into the default org's tree. To keep that true, no org may take the name of a folder in the default org's layout. POST /api/orgs and an orgs: entry both refuse these four slugs:

  • artifacts
  • baselines
  • scenarios
  • uploads

Per-job artifact overrides for a CI run (BE-0431)

A continuous integration (CI) run for a pull request pairs a build with a branch. It wants that build's binary, run against that branch's scenarios. POST /api/compose can deliver that pair, but it rebinds the org's active config. Every caller outside a signed-in browser shares that one binding. Two concurrent CI dispatches then race for it. Each bind also moves the org's remembered configuration.

POST /api/run accepts two optional fields instead. Each names an artifact by its sha256. The caller's org must already hold that artifact.

Field What the job gets
binaryArtifact a binary artifact, placed at the requested target's subject.path alone
scenariosArtifact a scenarios artifact (a zip), replacing that target's scenarios directory

A leg the request leaves out keeps resolving through the org's binding. Nothing writes the binding itself. Upload each artifact first through POST /api/artifacts/binary or POST /api/artifacts/scenarios. Probe GET /api/artifacts/exists to skip bytes already stored. The two fields need the editor role, the same role POST /api/run already requires.

curl -X POST "$SERVER/api/run" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"scenario": "added.yaml", "target": "demo",
       "binaryArtifact": "<sha256>", "scenariosArtifact": "<sha256>"}'

The control plane checks the request before any job exists:

  • A named artifact the org does not hold returns 400.
  • An object store that cannot answer returns a retryable 503. It never returns a 400 that claims the upload never happened.
  • With scenariosArtifact, serve looks up scenario among the zip's own entries. A scenario that exists nowhere else still runs.
  • The zip keeps the layout compose uses, with paths from the config's directory, such as scenarios/added.yaml. Every entry must sit under the target's scenarios directory, so the override cannot overwrite the bound binary or baselines.
  • serve refuses a single YAML Ain't Markup Language (YAML) file. A digest carries no file name to match scenario against.
  • binaryArtifact on a target with no subject.path, such as a web target, returns 400.
  • A single-process serve refuses both fields. It runs the job in the operator's own project directory, which no override may overwrite.
  • POST /api/run-set refuses both fields. Any worker serving the target's platform may lease a fan-out job, a Device Farm worker included. Mapping an override onto a Device Farm request is separate work.

The lease signs one presigned HTTP GET URL per named override: binary_url and scenarios_url. It signs each under the leased job's org. The worker checks each download against its sha256. It then builds the job a tree of its own, apart from the tree a job with no override uses. For a bundle job, that tree is a local copy of the cached bundle. The worker still fetches the bundle zip once.

A 404 ends the job. A digest mismatch leaves the lease to lapse, so another attempt can succeed. The run's manifest.json records binaryArtifact and scenariosArtifact under provenance. A bound bundle's identity sits beside them. Override trees live in the worker's .overrides/ directory. Prune it together with the .bundles/ cache.

1. Bring up the control plane

cd deploy/self-host
cp .env.example .env            # set BAJUTSU_SERVE_TOKEN, POSTGRES_PASSWORD, AWS_* (MinIO), bucket
mkdir -p config && cp /path/to/bajutsu.config.yaml config/   # the target list to expose
docker compose up -d            # postgres + minio + migrate (alembic upgrade head) + bajutsu

migrate runs the Alembic migrations to head before bajutsu starts, and minio-init creates the bucket. The control plane then listens on :8765.

To have the web UI's version badge (BE-0272) show which commit this image is running, pass that commit at build time (BE-0277) — the image ships no .git to read, so the badge falls back to this embedded value:

GIT_COMMIT=$(git rev-parse HEAD) docker compose build bajutsu   # then `docker compose up -d`

docker-compose.yml resolves GIT_COMMIT from the invoking shell (or a .env entry) into the bajutsu service's build arg. Leave it unset and the badge simply shows the version alone, as before. To build the control-plane image directly instead of through compose:

docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -f deploy/self-host/Dockerfile .

Published ports bind to BIND_ADDR (default 127.0.0.1). For a Mac worker to reach MinIO from another host, set BIND_ADDR in .env to the node's tailnet IP — never 0.0.0.0 on a host with a public interface, since a public bind would expose the artifacts bucket.

The artifact/scenario/baseline store — and, since BE-0243, uploaded zip bundles too — is named by one URI, BAJUTSU_SERVER_STORE (BE-0204) — s3://bucket/prefix (S3-compatible; MinIO, as shipped in this compose) or gs://bucket/prefix for a Google Cloud Storage bucket instead. Already running the rest of your stack on Google Cloud? Drop the minio / minio-init services from docker-compose.yml, point BAJUTSU_SERVER_STORE at your GCS bucket, and add the gcs extra to the control plane image's install line in deploy/self-host/Dockerfile (.[server,worker,db,oauth,gcs]) — no S3-compatible bucket needed at all.

Upgrading from a deployment that set the older BAJUTSU_S3_BUCKET / BAJUTSU_S3_PREFIX pair? Fold the prefix into the URI's path — BAJUTSU_S3_BUCKET=bajutsu + BAJUTSU_S3_PREFIX=tenant/ becomes BAJUTSU_SERVER_STORE=s3://bajutsu/tenant/; otherwise existing keys under that prefix stop resolving once the prefix is dropped.

2. Add GitHub OAuth (optional)

The shared token (BAJUTSU_SERVE_TOKEN) alone is enough for a couple of operators. For per-user browser login, create a GitHub OAuth app (callback https://<your-host>/api/oauth/callback) and set in .env: BAJUTSU_OAUTH_GITHUB_CLIENT_ID / _SECRET / _REDIRECT_URI.

Once OAuth is configured, access follows GitHub organization and Team membership (BE-0313) rather than a hand-maintained login list:

  • Sign-in and the viewer role follow org membership. A user may sign in only as a member of a configured org — an explicit members entry, a member of a githubOrgs-listed GitHub org, or a direct member of a githubTeams-listed or editorTeams-listed GitHub Team (see orgs:) — and a successful sign-in grants viewer (read-only). githubTeams is the narrow unit: it admits one Team without admitting its whole GitHub organization, which is what a shared organization needs when only one Team of it should reach this deployment. While GitHub's Teams API errors, /user/teams fails closed, so a login whose only membership is a Team is turned away for as long as the outage lasts. A login that matches no org is turned away, so an OAuth deployment must declare an orgs: block — with one exception, a member of a configured admin Team, who clears this gate regardless (see Admin below). A deployment that also wires a database keeps this membership in the database instead, seeded once from that same orgs: block and administered from the web UI afterward (see Multiple orgs below); which org owns which target still comes from the block either way.
  • Editor follows the org's editorTeams: a direct member of any of those flat GitHub Teams may run, record, and edit scenarios. editorTeams admits as well as promotes, so a Team named there needs no second entry under githubTeams to be able to sign in. It holds a list rather than one Team so that an org spanning more than one GitHub organization can name the writing Team of each. A configuration on the older singular editorTeam still works: serve folds that key into editorTeams. Rename it anyway; the plural name is the documented one.
  • Admin follows one or more server-wide GitHub Teams, BAJUTSU_OAUTH_ADMIN_TEAMS (a comma-separated list, each written "<github-org>/<team-slug>", where <team-slug> is GitHub's own lowercased slug and not the Team's display name; like githubTeams and editorTeams, each entry names one flat Team — a Team nested beneath it does not match — and is compared case-insensitively, as GitHub itself resolves an org login and a Team slug), whose members also change server settings (config / API key / provider). Admin is a single deployment-wide tier, so name only Teams whose members you trust across every org. Unlike the viewer/editor roles above, a member of any configured admin Team clears the sign-in gate directly — the Team itself does not need to appear in any org's members, githubOrgs, githubTeams, or editorTeams — so an admin can sign in and repoint the server at a corrected config even when the orgs: block is broken or missing entirely. One failure still closes that door: /user/teams fails closed, so while GitHub's Teams API is erroring, a login whose only claim is admin-Team membership is turned away like any other. Because of that, BAJUTSU_OAUTH_ADMIN_TEAMS is now a sign-in credential and not only a role mapping: every entry's GitHub-organization half must name an organization you actually control, since anyone who controls it can create a Team with the matching slug and sign in as admin.

Membership is re-read on every login, so leaving a GitHub org or Team takes effect at the affected user's next sign-in — no server-side list to edit. Login always requests the read:org scope to read these memberships, so the consent screen mentions organization access.

Upgrading from the login lists. Two things change beyond the role-source swap: sign-in now admits everyone in a configured members / githubOrgs / githubTeams / editorTeams entry, not just the logins that were on the old BAJUTSU_OAUTH_ALLOWED_USERS — if that allowlist was narrower than the org's full membership, tighten orgs: before switching, or the org gate alone will widen who can sign in. And BAJUTSU_OAUTH_ALLOWED_USERS / _ADMINS / _VIEWERS are simply ignored now, so re-declare every admin and editor as a Team membership before cutting over — anyone not yet covered by editorTeams or BAJUTSU_OAUTH_ADMIN_TEAMS drops to viewer on their next login. A deployment that already set the older, singular BAJUTSU_OAUTH_ADMIN_TEAM renames it to BAJUTSU_OAUTH_ADMIN_TEAMS at the same time — the old name is no longer read. serve warns on stderr at startup when the retired name is still set, when BAJUTSU_OAUTH_ADMIN_TEAMS resolves to an empty list, when an entry is not a well-formed "<github-org>/<team-slug>" pair, and when GitHub OAuth is only partly configured — one of BAJUTSU_OAUTH_GITHUB_CLIENT_ID / _CLIENT_SECRET / _REDIRECT_URI left unset 404s every GitHub sign-in and silently re-enables the shared-token login instead (or, with no BAJUTSU_SERVE_TOKEN set either, leaves every endpoint unauthenticated). Read the first lines of the log after upgrading. Each of these warnings is also re-emitted through the structured log under event=server.startup_warning (with a stable check field naming which one — see Operational logging), so a deployment can alert on them rather than relying on someone reading boot output. A sign-in the org gate turned away is recorded under event=oauth.denied, naming the reason the org model did not match — the orgs: block, or the org table on a deployment whose database holds the membership; it is WARNING only when no admin Team is usable — the list is empty, or every entry is malformed, so no admin can sign in to fix orgs: either — and INFO for an ordinary denial (a configured admin Team simply didn't match this login) and for four earlier failures reachable with no GitHub account at all — OAuth not configured, a CSRF state mismatch, an exchange that raised, and one that returned no identity. Anyone with a GitHub account can otherwise reach an ordinary denial, so key an alert on WARNING rather than on the bare event name, or a curious visitor's sign-in attempt buries the shape worth paging on.

A third thing: disabling POST /api/login stops minting new token-cookie sessions once OAuth is configured, but it doesn't invalidate one already issued — a browser that logged in with the shared token before OAuth was turned on keeps that session's full, unchecked access (a token-minted session carries no identity, so the role gate never applies to it) until it expires on its own (BAJUTSU_SESSION_TTL, seven days by default). A deployment moving from token-only to OAuth should rotate the session store (or otherwise force-clear existing cookies) at cutover, rather than count on the seven-day window to close it.

Once OAuth is configured, the shared token narrows to worker traffic only: it authorizes the worker control-plane routes (the /api/worker/* endpoints and the run evidence-upload URL request) and nothing else. The browser token-login endpoint (POST /api/login) is disabled — a human signs in exclusively through GitHub OAuth — and a raw Authorization: Bearer <token> no longer reaches any non-worker endpoint. A deployment that scripted non-worker endpoints with the token loses that path once OAuth is on. Without OAuth (the single-Mac, private-network shape) the token is unchanged and still reaches everything.

Authenticating a CI job (optional, BE-0414)

A continuous-integration (CI) job is neither of the two callers above. It cannot complete a browser sign-in, and the paragraph just above is its problem: once OAuth is on, the shared token no longer reaches a non-worker endpoint. Rather than hand every pipeline a long-lived secret, BE-0414 lets a job authenticate with the OpenID Connect (OIDC) token its CI platform already issues it, and exchanges that once for a short-lived machine session. The pipeline stores no secret at all, and the deployment learns which repository acted rather than only that "the token" did.

On the CI side there is nothing to register — no GitHub App, no OAuth app, no identity provider. A GitHub Actions job declares one permission and asks for a token:

jobs:
  e2e:
    runs-on: ubuntu-latest
    permissions:
      id-token: write        # the whole GitHub-side setup
    steps:
      - name: Exchange the OIDC token for a Bajutsu machine session
        run: |
          set -o pipefail
          token=$(curl -sSf -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$BAJUTSU_AUDIENCE" | jq -er .value)
          curl -sSf -c cookies.txt -X POST "$BAJUTSU_URL/api/oidc/exchange" \
            -H 'Content-Type: application/json' \
            -d "{\"token\": \"$token\", \"org\": \"acme\"}"
        env:
          BAJUTSU_URL: https://bajutsu.example.com
          BAJUTSU_AUDIENCE: https://bajutsu.example.com

Every later call in the pipeline presents the cookie, never the OIDC token again.

On the serve side, set the audience — that one variable is what turns the whole caller shape on:

Variable Default What it does
BAJUTSU_OIDC_AUDIENCE (unset) The aud a token must carry. Unset disables OIDC entirely: the exchange endpoint is not even reachable.
BAJUTSU_OIDC_PROVIDER github-actions Which CI platform's claim names to read. GitHub Actions is the only one today.
BAJUTSU_OIDC_ISSUER the provider's own Override for a self-hosted installation — GitHub Enterprise Server issues from its own hostname.
BAJUTSU_OIDC_MAX_TOKEN_AGE 300 Seconds since the token's iat past which it is refused, independent of its own exp.
BAJUTSU_OIDC_SESSION_TTL 900 Seconds the minted machine session lives. Capped by both the token's own exp and the deployment-wide BAJUTSU_SESSION_TTL, so the shortest of the three wins.

Set the audience deliberately. The workflow chooses the audience it asks GitHub for, so a deployment that accepted any would accept a token some unrelated service minted for itself. There is deliberately no default: leaving it unset switches the caller shape off rather than falling back to "accept whatever arrives".

The exchange needs a database, and the oauth extra. Each token's jti is spent in the shared system of record, so single-use holds across control-plane replicas rather than only within one process. Every server has that database, and a deployment with a bucket must name one. A server on one machine with no bucket keeps a default SQLite. Its exchange then works within that single process (see The server backend on one machine, above). The token signature is verified with joserfc, which ships in the oauth extra (uv sync --extra oauth), the same extra GitHub OAuth needs. serve warns at boot when the extra is missing. A pipeline then need not discover the gap one failed run at a time.

Then list the repositories each org admits, under allowedRepositories:

orgs:
  acme:
    members: [alice]
    allowedRepositories:
      - acme/app                         # any workflow in this repository
      - repository: acme/web             # …or narrowed further
        environment: production

An entry is either the bare "<owner>/<repo>" name or an object carrying that name plus a bound — environment, ref, or workflowRef (GitHub Actions' job_workflow_ref claim). A bound applies to its own entry only, so one org can list a reviewed-environment repository beside an unbounded one. Matching is exact equality on the token's discrete claims, never a parse of sub and never a prefix — acme/app does not admit acme/app-evil.

The exchange request names the org, and naming it selects, it never grants: that org's own allowedRepositories is what admits the token. Requiring the name is what lets one shared pipeline repository serve several orgs, which inferring the org would have to forbid.

Like the membership lists beside it, the roster lives in the database once one is wired, so an admin edits it through POST /api/orgs/<slug>/membership without a redeploy. Omitting allowedRepositories from that body leaves it untouched — only sending the key, [] included, replaces it — so a client that predates the field cannot silently revoke every pipeline.

Three hazards worth reading before you list a repository:

  • A repository name is mutable. Deleting, renaming, or transferring a repository frees its name, and whoever claims it next can mint tokens matching your entry. Update or remove an entry the moment its repository changes.
  • Whoever can merge a workflow can mint a token. allowedRepositories: [acme/app] means "whoever can write that repository's workflows may act as this org". Narrow by environment when that is too broad — a GitHub Environment can require reviewers before the job runs.
  • Fork pull requests. A fork's pull request does not get id-token: write by default. A pull_request_target workflow does, because it runs in the base repository's context, and so does any workflow in a repository configured to send write tokens to fork pull requests. Narrow such a repository by environment so no token is ever minted from a run an outside contributor influenced.

An allowlist of endpoints governs a machine session, never a role. A pipeline is not a person, and no viewer / editor / admin rank describes one. Four of the endpoints below are admin today. Granting a machine that rank would carry config rebinding and the secret reads with it. Naming endpoints keeps a pipeline's reach to what a pipeline needs:

A machine session may and is refused
GET /api/artifacts/exists — probe for a build it already published POST /api/config, POST /api/compose — rebinding the org's active configuration
POST /api/artifacts/config, .../scenarios, .../binary — publish the three artifact kinds GET /api/config/content — a config body may embed secrets
POST /api/run and POST /api/run-set — dispatch a run or a group of runs POST /api/apikey, POST /api/claudecodetoken — operator secrets
GET /api/runs, GET /api/jobs/<id>, and GET /api/run-set/<groupId> — watch what it dispatched /api/orgs* — who may sign in and write

The right-hand column is not a list serve keeps. The allowlist denies by default. An endpoint stays shut to a machine by never appearing on the left, and a route added next year stays shut until someone opens it on purpose.

The org travels with the session. The exchange settles which tenant a pipeline acts as. Every allowlisted call reads that answer rather than deriving its own. A run a machine dispatches lands in that org, and the runs and jobs it reads are that org's alone. A job belonging to another org answers 404, which a job id that never existed answers too — a "forbidden" would confirm the id.

An audit entry names the repository, not a user. The user table holds no row for a pipeline, and actor_id is a foreign key into that table. The column stays null, and the repository goes into the entry's detail payload. A synthetic user filling that column would join the roster /api/orgs discloses. serve audits the probe beside the uploads, so a pipeline that finds its build already stored still leaves a trace.

An audit entry names the job, too. One repository runs many jobs, so the repository alone cannot tell a rerun from the run it retried. The exchange keeps the job's claims from the token on the session, and every entry that session writes carries them under actor in the detail payload. The exchange itself writes an oidc.exchange entry with the same record. If that one write fails, the exchange still returns the session and logs the failure at ERROR as oidc.audit_failed, because the token is already spent and a 500 would leave the job unable to retry.

{
  "repository": "acme/app",
  "actor": {
    "runId": "123",
    "runAttempt": "1",
    "checkRunId": "456",
    "ref": "refs/heads/main",
    "workflowRef": "acme/app/.github/workflows/e2e.yml@refs/heads/main",
    "sha": "…",
    "triggeredBy": "octocat"
  }
}

runId and checkRunId together name one job, and runAttempt tells a rerun from the run it retried. On github.com the job's page is https://github.com/<repository>/actions/runs/<runId>/job/<checkRunId>; a GitHub Enterprise Server serves the same path on its own host. serve stores the parts rather than that link, because the host is not in the token. A claim the token lacks is left out of the record rather than written as null.

Ending a machine session. A GitHub-issued token runs until it expires, whatever you do. A machine session is one serve minted, and serve can revoke it:

# -b: the admin's own signed-in session cookie, as for every other /api/orgs call.
curl -X POST "$BAJUTSU_URL/api/orgs/acme/machine-sessions/revoke" -b cookies.txt \
  -H 'Content-Type: application/json' -d '{"repository": "acme/app"}'

An admin action, like the rest of /api/orgs/…, so it needs an admin's session rather than the pipeline's. Match the repository the way your roster spells it: casing is folded on both sides. Omitting repository ends every machine session in the org, the reach you want when the roster itself is what went wrong. Retiring an org ends its machine sessions too.

Two bounds shape what a revocation reaches:

  • One org at a time. A repository listed by more than one org keeps the sessions it minted for the others. One org's admin cannot end another org's pipelines.
  • Per repository, not per job. Every session a repository mints carries the identity repo:<owner>/<repo>, and a revocation ends that repository's concurrent pipelines together.

Removing an allowedRepositories entry stops new sessions and leaves live ones running, because configuration binds at the exchange. Revoking is the second half of that operator duty. Rename, transfer, or delete a listed repository, and you remove the entry and revoke what it minted.

Operator secrets (the Claude API key)

The API key an admin sets through the settings panel is an operator secret, and on the hosted control plane it is write-once and encrypted at rest (BE-0136). No endpoint ever returns the plaintext again — for any role, admin included — only a masked preview; to rotate a key an admin overwrites it, never reading the old one back. The value is stored in the database's secrets table encrypted with authenticated encryption (Fernet) and scoped per org, so it survives a restart and is shared across control-plane replicas.

That encryption needs a master key, provisioned outside the database like BAJUTSU_DATABASE_URL:

# generate once, then keep it in .env / your platform's own secret store
python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'
export BAJUTSU_SECRETS_KEY=…

A database-backed control plane requires BAJUTSU_SECRETS_KEY and refuses to start without one, rather than silently degrading to holding the secret only in process memory. A server on one machine with no bucket keeps its secrets in its default SQLite. It encrypts them under a key it generates into .bajutsu/secrets.key. Treat the key like the database password: losing it makes the stored secrets unrecoverable, and a rotated key cannot decrypt values written under the old one, so re-enter each secret after rotating.

The settings panel holds a second write-once operator secret the same way: the Claude Code OAuth token (CLAUDE_CODE_OAUTH_TOKEN), for a deployment that runs the claude-code provider on a browser-less host and so can't complete claude setup-token's interactive sign-in (BE-0215). It is stored, masked, and rotated exactly like the API key above.

The same store also holds a scenario's own declared secrets (BE-0274) — the evidence.secrets names a config lists for ${secrets.X}. Previously the only way to supply these was the .env the process inherited; now an admin sets each one from the settings panel's Scenario secrets section, and on the hosted control plane it lands in the same per-org encrypted secrets table (reusing BAJUTSU_SECRETS_KEY, already required above — no new key), write-once and masked like the operator credentials. A run reads every stored secret on the worker that leases it (BE-0449). The control plane decrypts the org's secrets at lease time. It hands them over in the lease response, so the plaintext never rides the job queue. The worker lays the values over the spawned run's environment. The API key, the Claude Code token, and each ${secrets.X} then resolve there. A lease taken with the shared token receives the values, and a browser login does not. The stored Git config-source token reaches the control plane's own fetch, never a job.

3. Run a Mac worker

On each Mac (the same Aqua-session setup as Tier A — auto-login, caffeinate/pmset), install the iOS worker's runtime closure bajutsu[worker-ios] (the iOS (XCUITest) worker needs no backend pip extra, so this is just the visual / schema assertion deps a run reaches, BE-0173) and point it at the control plane over the tailnet:

export BAJUTSU_SERVER_URL=http://<linux-node>.<tailnet>.ts.net:8765
export BAJUTSU_TOKEN=…         # the same operator token the control plane uses
export ANTHROPIC_API_KEY=…     # only if scenarios use the AI paths (record / --system-alert-handling)
bajutsu worker

The worker holds no object-store credentials (BE-0160): no BAJUTSU_SERVER_STORE / BAJUTSU_S3_ENDPOINT / AWS_*, and no cloud SDK. It downloads the run's baselines, uploads the finished runs/<id>/ tree, and persists a record job's authored scenario over presigned URLs the control plane signs — the control plane is the only place the object store's credentials live. The bytes still flow worker→storage directly (the signed URL points at MinIO), so the worker needs network reachability to the object store, just not its secrets.

A run off an uploaded bundle travels the same way. The control plane binds a dropped zip, or a composed (config, scenarios, binary) triple. It keeps that tree on its own disk, out of any worker's reach. The lease carries one signed read URL per stored object the bundle holds.

The worker rebuilds the tree under .bundles/<org>/<id>/ in its working directory. It runs the job from the tree's root. The config's relative subject.path, paths.scenarios, and paths.baselines then resolve as written. The bundle's content digest keys that tree, so a second run off it downloads nothing. The digest also keeps two builds apart. Two bundles whose binaries share a path but differ in bytes never share a workspace.

This path needs an object store configured. A control plane running without one has stored the bundle nowhere. Such a job now fails with bundle unavailable, instead of at install time.

Two notes for operating it:

  • Nothing evicts a tree. A pipeline that uploads a bundle per build accumulates one tree per build. Prune .bundles/ on a schedule if the worker's disk is tight.
  • A bundle's run no longer downloads the organization's stored baselines. The bundle ships its own. If you approve baselines through serve and also upload bundles, put the approved images in the bundle.

To declare what one machine can run, pass a worker capability file with bajutsu worker --worker-config <worker.yaml> (BE-0450). The file lists the drivers the machine offers. Its maxTargetsPerJob caps the targets one scenario may hold at once. Without the flag, the worker uses the shipped default. The default offers every driver and sets no target limit. The worker validates the file at startup, before it leases any job. It hands the file's absolute path to every bajutsu run it spawns. Each leased run checks its scenarios against the file. A scenario that needs a driver this machine cannot run fails with a worker-capability-unsupported: reason. The control plane never reads the file. Drivers describes the file format and the check.

A worker whose file sets environment: devicefarm also reads its job budget there (BE-0448). The file's top-level maxJobConcurrency caps the jobs that worker holds at once. While every slot holds a job, the worker sends no lease request. Above one, the worker runs each job on its own thread and in its own .slots/<n>/ workspace. A stop signal to such a worker lets its leases lapse instead of cancelling the jobs. A restarted worker then resumes the runs. Running on AWS Device Farm covers the budget and the check before each submission.

Wrap it in a LaunchAgent (as in Tier A) so it survives reboots. The worker polls the control plane's /api/worker/lease endpoint over HTTP (no Redis needed), runs each job on a fresh Simulator, uploads the runs/<id>/ tree (including console.log), and posts the result back to /api/worker/result. The control plane records the finished run into Postgres — the worker needs no database access.

The browser shows a queued job's console live (BE-0449). While a job runs, the worker posts its new log lines to /api/worker/log about once a second. The worker masks credential shapes first. A private key block stays masked up to its END line. The control plane accepts a batch from the lease holder alone. Any other worker gets 409 and drops the job, as on a heartbeat 409. One post carries at most 500 lines and 4 MiB; the worker splits a larger batch, and the control plane refuses a larger body with 413 before reading it. The control plane cuts a line longer than 8 KiB. A job may publish 50,000 live lines or 16 MiB. Past that, a single truncation notice replaces the rest. Each line goes to the job's Server-Sent Events (SSE) stream. The worker's result closes the stream. The worker logs and drops a batch it cannot post. A lost batch never stops or delays the job.

The live lines serve a viewer who watches the job while it runs. The uploaded console.log stays the durable copy of the log:

  • A viewer who opens a finished job gets console.log when it exists.
  • A viewer who watched live gets console.log at the end when no live line reached that viewer.
  • A viewer who received some live lines does not get them again from console.log.

Live logs on more than one control-plane replica need BAJUTSU_REDIS_URL. One process keeps the live lines in memory. Replicas behind a load balancer need a shared store instead:

  • Set BAJUTSU_REDIS_URL on every replica, for example redis://cache:6379/0.
  • Install the redis package beside the server extras (pip install redis).

A worker's post and a browser's stream then meet in Redis, whatever replica each one reaches. Without Redis, a browser misses the lines a worker posted to another replica. Each replica applies the cap to its own tally.

A cancel reaches a job whether the job waits in the queue or runs on a worker. The control plane finds the job in the jobs table. A cancel thus reaches a job queued before a restart too.

  • A queued job: the control plane marks the job cancelled, and no worker leases it.
  • A leased job: the job keeps its lease, and the control plane flags it. The next worker heartbeat answers {"ok": true, "cancel": true}, and the worker stops its own run. A run job winds down and still writes its report. Any other kind of job stops with its whole process group. The worker renews the lease until the run ends. It then posts a cancelled result. The control plane accepts that result from the lease holder alone, and marks the job cancelled.
  • A finished job: the cancel changes nothing and reports the job's final status.

A worker can go offline while it stops a cancelled job. Once the lease expires, the control plane ends the job cancelled. Another worker never runs it.

A leased-job cancel needs workers at this version or later. Upgrade the workers together with the control plane.

4. Expose it

Front the control plane like Tier A: tailscale serve --bg 8765 (tailnet-only, recommended), or Caddy for a real hostname (docker compose --profile caddy up -d, with BAJUTSU_PUBLIC_HOST set). The worker reaches the control plane (:8765) and MinIO (:9000) over the tailnet, so keep the node on the private tailnet.

5. Add a Linux web worker container (optional)

The web (Playwright) backend runs headless on Linux, so its worker is a container rather than a bare-metal Mac (BE-0173). The compose stack ships an optional worker-web service, off by default (behind a profile), so an iOS-only deploy is unchanged. Enable it — on the Linux node or any other Docker host that can reach the control plane — with:

cd deploy/self-host
# BAJUTSU_SERVE_TOKEN must be set in .env — the web worker reuses it as its operator token
docker compose --profile web-worker up -d --build

The service builds worker-web.Dockerfile, a multi-stage image that installs only the worker's runtime closure (bajutsu[worker-web] = the web backend + visual + schema) and the headless Chromium the browser needs. It deliberately omits the control plane's stack (server / db / oauth), the cloud SDKs, and the AI SDK — the worker talks to the control plane and object store over plain HTTP and, per BE-0160, holds no object-store credentials (it needs only BAJUTSU_SERVER_URL and BAJUTSU_TOKEN). To keep the image small it installs Chromium's headless shell (playwright install --with-deps --only-shell chromium) instead of the full headed build: the shell is what Playwright already uses for headless runs, so nothing in a run changes, and it saves tens of MB of browser plus a lighter system-library set. A Linux worker is always headless, so the headed-only features the shell drops don't apply. The image installs only the Chromium shell, so it serves Chromium web runs (the default engine); a scenario pinned to Firefox or WebKit (BE-0076) needs a worker with those browsers, not this slim image.

To run a web worker outside compose (e.g. a separate Linux box), build and run the image directly:

docker build -f deploy/self-host/worker-web.Dockerfile -t bajutsu-worker-web .
docker run -d --rm \
  -e BAJUTSU_SERVER_URL=http://<linux-node>.<tailnet>.ts.net:8765 \
  -e BAJUTSU_TOKEN=… \
  bajutsu-worker-web

A web worker leases only web jobs and a Mac iOS worker only iOS jobs — the pool routes by capability, so a mixed-backend fleet is safe (see capability-routed queues below).

Capability-routed queues (BE-0166)

A real Mac pool is rarely uniform: machines carry different iOS runtimes, some are set up for iPad and others for iPhone, and a web worker runs a different backend entirely. With one undifferentiated queue any worker could lease any job, so an iOS job could land on a Linux web worker and fail — not for a real defect, but because it was routed to the wrong machine. Capability routing stops that: a job is only ever leased by a worker that can actually run it.

Each worker advertises a set of capability tokens when it polls for work, and a job carries the set it requires; the control plane leases a job to a worker only when the worker advertises every token the job requires. Routing decides which idle worker picks a job up — it never changes the deterministic run verdict.

  • A worker's advertised set comes from its --platform and from the machine itself. The --platform value gives the backend axis: platform:ios for a Mac iOS worker, platform:web for the Playwright container. Every worker advertises host:<os> for the operating system it runs on, such as host:darwin on a Mac (BE-0450). An iOS worker also advertises its installed Simulator inventory. That inventory gives an iosNN token per runtime, and the iphone and ipad device classes. An iOS worker also advertises device:iphone and device:ipad for the families of the real devices connected to it, read over devicectl. Real devices come and go, so the worker reads them again on its lease polls, at most once every 15 seconds, and logs each change in what it reads (BE-0468). A worker on a local start's machine also advertises machine:<id>, the server's identity, which routes the jobs that name files on that machine (the server backend on one machine). The web-worker container bakes in --platform web, so it advertises web and needs no flag.
  • A worker also advertises what a fan-out job needs. Every worker advertises job:run-intent. The token says it can turn a fan-out job into its own kind of run (BE-0484). An iOS worker advertises kind:simulator when its inventory holds an iPhone or iPad Simulator. It advertises kind:device while it reads a real iPhone or iPad over devicectl. A worker capability file that sets realDevices: false turns that token off. A Device Farm worker advertises platform:android, platform:ios, and kind:device. These are the platforms and the device kind the service reserves.
  • A local worker refuses a platform it cannot serve. At startup, the worker checks each --platform against its worker capability file and its host. When the file omits the platform's driver, or the host cannot run that driver, the worker exits with a message that names the driver. A Linux machine started with the default --platform ios thus stops with xcuitest runs only on macOS; this worker runs on linux. It does not idle on jobs it could never start. The check reads the platform's drivers, so an iOS target on the fake backend still waits for a Mac worker.
  • A job's required set is the target's platform axis and its driver's operating system. The target's platform decides its driver. When that driver runs on one operating system alone, the set also holds host:<os>. An iOS target on the xcuitest driver thus requires host:darwin. A web or Android target adds no host: token. A worker on the matching machine leases the job. The worker's own check still judges each scenario before any device work. A target declares no extra tokens, since requires: and defaults.requires are gone (BE-0452). Routing derives no ios18 token from runsOn.ios.os, so no job routes on an iOS runtime.
  • A job's required set also holds the target's runsOn.ios.family. A serve job runs every kind the target's runsOn.ios.kind lists. One worker thus needs a fitting device for each. A Simulator run requires the inventory's iphone or ipad token. A real-device run requires the device: one. A single family requires its token, so kind: device with family: ipad requires device:ipad. A family priority list accepts any one family, which a subset test cannot express. The job instead stores an any-of group, anyof:device:ipad|device:iphone, which a worker meets by advertising any one member. The leasing worker still resolves the list over its own pool, so routing picks the worker and the list picks the device. A target that names no family adds no token. A request that sends the target to the fake driver adds none either, because that driver drives no device (BE-0468).
  • A fan-out job requires no placement. A job of POST /api/run-set requires its target's platform:<p>, job:run-intent, and the cap: and setting: tokens of its scenario's route (below). An iOS job adds the family tokens above and one kind:<kind> token per kind its runs take. It requires no host:, environment:, or machine: token. A worker serving the platform can lease it, local or Device Farm, when it advertises those tokens. A Device Farm worker advertises no family token, so a target naming runsOn.ios.family never routes there. A worker that advertises an environment: token otherwise leases only the jobs requiring that token. A fan-out job is the exception, since it names no environment (BE-0484).
  • A paired device reads as connected. devicectl lists every paired real device, plugged in or not. Its tunnel state reads disconnected until a run opens the tunnel. An idle device and an unplugged one look alike there. A worker keeps advertising an unplugged device's family. A job routed to that worker fails when its run drives the device. The job does not stay queued.
  • A run job also requires what its steps and settings need on its route (BE-0467). Each target resolves to an environment route: ios-simulator, ios-device, ios-live (a WebDriver endpoint), android, or web. A platform alone is not enough, since the three iOS routes support different settings. The job requires two kinds of token:
  • cap:<route>:<capability> for each capability the steps routed to that target need;
  • setting:<route>:<key> for each setting it puts in effect that the target does not declare under runsOn.ignoredSettings.

A run on an Appium grid puts its iOS targets on ios-live. - A worker advertises one token set per route its drivers drive. xcuitest drives the Simulator route, adb drives android, and playwright drives web. The drivers are every one its worker capability file offers and its host can start, whatever its --platform, since a scenario's other targets run on the same machine. An xcuitest worker adds the ios-device route unless its file sets realDevices: false, and an appium worker advertises ios-live. The route set is as accurate as the file, so list the drivers the machine has installed, and no others. Every such worker also advertises cap:routing, which marks it as computing route tokens; no job requires that token. The sets are never intersected. A Mac serving the Simulator and an attached iPhone thus never takes an erase job on the device route, and still takes every Simulator job. - A mismatch fails at submission, and an unserved route waits. The control plane refuses a job when three conditions hold together: - a live worker already drives the job's route; - no live worker advertises every token the job needs; - no live worker can serve the job at all. A worker from before this item matches on its other tokens, so while one still serves the job, a mixed fleet accepts it.

POST /api/run then returns 400. The error lists each missing token with the steps or settings that need it. POST /api/run-set checks each of its jobs the same way. One refused job refuses the whole request with 400. The error names the scenario and its missing tokens. While no live worker drives the route, the job stays queued and counts toward bajutsu_unroutable_jobs. A cold start or a worker restart is such a case. - A worker re-checks a job when it claims it. The lease hands the worker the tokens the server routed the job by. Before the worker fetches anything or leases a device, it recomputes its route tokens from its worker.yaml and the drivers its host can start. A job needing a token the worker no longer offers fails with that token's name. - A run on an Appium grid routes by environment. The plain run request (POST /api/run) takes an optional environment. Its one accepted value is appium; any other value returns 400. Such a job requires environment:appium alone, since the grid owns the device. An appium worker sets environment: appium and the grid's endpoint in its worker.yaml. It advertises that token and job:run-intent, and takes no --platform. It advertises no platform: token, so it takes no fan-out job. It runs a local bajutsu run with its --worker-config (iOS on a real device). A fan-out (POST /api/run-set) takes no environment. It routes each job by its target's platform (Running on AWS Device Farm). - A hand-written worker input now logs a deprecation notice. A worker's --capabilities and $BAJUTSU_WORKER_CAPABILITIES add tokens verbatim. Both still work for this release, with a one-time notice, and go away in the next release. The inventory and the worker capability file now supply what the override was for. An override can also claim a runtime the machine lacks. Neither may carry the reserved environment:, host:, machine:, device:, cap:, setting:, job:, platform:, or kind: prefix, which the worker fills itself. A worker rejects such a token at startup. - An unroutable job — one whose required capabilities no live worker advertises — stays queued rather than being leased to an incompatible worker or dropped, and is surfaced by the bajutsu_unroutable_jobs metric (below) so the operator knows to add a worker with the missing capability. A homogeneous pool is unaffected: every worker advertises the same axis, so every job routes as before.

[!NOTE] Upgrade the workers alongside or before the control plane. Every dispatched job now carries at least its platform:* requirement, and a worker on a pre-capability-routing build sends no advertised set — so it advertises nothing and can lease no real job. The same holds for BE-0450: an iOS job on xcuitest now requires host:darwin, which a worker built before that change never advertises. It fails safe (it never mis-routes), but an old worker left running against an upgraded control plane silently stops leasing, showing up only as a rising bajutsu_unroutable_jobs. Roll the worker binaries first (or together), not after. The same order holds for BE-0449: the control plane now queues a run as python -m bajutsu.run.internal, which a worker built before that change cannot map onto its own interpreter, so such a worker fails every run it leases.

BE-0467 goes the other way. A worker built before it advertises no cap: or setting: token, and the control plane matches such a worker on the other tokens alone, so an upgrade never strands a queue. The lease records workerRouting: unchecked on each such job's provenance, which reaches the run's manifest.json. A report rendered on view, as a local serve renders it, lists that record under notices. The report baked at run time does not, since the old worker baked it before the record arrived. Roll the workers to stop the record.

BE-0484 needs the workers first again. A fan-out job requires job:run-intent, which a worker built before that change never advertises. A Device Farm worker built before it advertises no platform: token. In both cases the fan-out jobs stay queued and count toward bajutsu_unroutable_jobs. A worker started with --capabilities platform:… or kind:… used to start, and now refuses to start. Remove the token, since the worker fills both prefixes itself.

Evidence upload to object storage (optional, BE-0110)

The worker upload above writes each run tree to the artifact store the control plane serves reports from. Separately, you can archive every run's evidence to a lifecycle-managed bucket — retain main-branch evidence for audit, expire feature-branch evidence after a few days — by setting one URI on the control plane:

# on the control plane (docker compose env, or the serve process)
export BAJUTSU_EVIDENCE_STORE=s3://audit-bucket/evidence/   # or gs://…; --evidence-store also works

The evidence store is a second, independent destination from the artifact store: it can be a separate account or a stricter-permissioned, lifecycle-managed bucket. Both are credential-free for the worker — the control plane holds each bucket's credentials and signs a presigned PUT URL per file, and the worker uploads over plain HTTP (BE-0110 for evidence, BE-0160 for the artifact store). Install the s3 or gcs extra on the control plane (uv sync --extra s3 or --extra gcs); the worker needs neither.

A CI job picks the per-run path — and thus the lifecycle policy — by passing evidence_prefix when it starts a run:

curl -X POST "$SERVER/api/run" -H "Authorization: Bearer $TOKEN" \
  -d '{"scenario": "smoke.yaml", "target": "demo", "evidence_prefix": "main/abc1234/"}'

The control plane validates evidence_prefix as a safe relative segment and prepends its own bucket + base prefix, so the final key is evidence/main/abc1234/<runId>/… — the run id is always in the path, so runs never collide, and a caller can't escape the base prefix. The upload runs after the verdict, so a failure is logged and never changes pass/fail. When BAJUTSU_EVIDENCE_STORE is unset the worker still asks and simply uploads nothing.

Multiple orgs

To host more than one team on one backend, declare orgs in the mounted config — each with its member GitHub logins, GitHub orgs, and/or GitHub Teams, plus the targets it owns (see configuration):

orgs:
  acme:
    members: [alice, bob]
    githubOrgs: [acme-gh]    # everyone in this GitHub org (login requests the read:org scope)
    targets: [demo, checkout]
  globex:
    members: [carol]
    githubTeams: [shared-gh/globex-qa]    # one Team of a shared org, not the whole org
    targets: [other]

Each user is then scoped to their org: they see only that org's targets, a cross-org run/scenario/ artifact reads as not-found or returns 403, and each org's artifacts/scenarios/baselines live under its own object-store prefix. With no orgs: block the backend stays single-tenant (one default org), and the shared token plus the GitHub allowlist are the access boundary. The fully managed public cloud offering (a hosted Mac worker pool + IaC) is still future work in BE-0015.

Managing orgs from the web UI, once a database is wired. A backend with BAJUTSU_DATABASE_URL set keeps each org's membership — its members, githubOrgs, githubTeams, and editorTeams — in that database rather than in the config file, so onboarding a tenant or moving a team's write access to a different GitHub Team no longer needs a config edit and a redeploy (BE-0375). An Orgs page appears in the web UI for admins, backed by four admin-only endpoints:

Request What it does
GET /api/orgs List every live org with its membership.
POST /api/orgs Create an org from {"slug": "...", "name": "..."}, with no members — so it admits nobody until you set its membership.
POST /api/orgs/<slug>/membership Replace {"members": [...], "githubOrgs": [...], "githubTeams": [...], "editorTeams": [...]} as one unit. allowedRepositories is the exception: omitting the key leaves the machine roster untouched, and only an explicit list — [] included — replaces it. A body still carrying the retired singular editorTeam is refused with a 400: it names no editorTeams, and obeying it would strip the org's write access.
DELETE /api/orgs/<slug> Retire an org. Refused outright for default.

The audit log records every one of the four. default is reserved on all three mutations — created, re-membered, and retired are each refused for it. It is the org an unmatched sign-in falls into, including every admin admitted by the admin-Team bypass, so a real tenant there would take the namespace an admin recovers through; giving it a roster would do that just as surely as creating it, since membership is what places a login in an org. It is still listed, marked as the fallback, because a bypassed admin is sitting in it and hiding that would hide where their own runs, secrets, and evidence land. Deleting an org is a soft delete: it stops admitting sign-ins and leaves the list, and every session its members already hold is revoked at the same moment, so nobody keeps acting as the retired tenant on a cookie issued before it. Its runs and audit entries stay queryable — an admin action removes a tenant's ability to act, not the record of what it already did — and its slug stays reserved, so it cannot be re-created under the same name.

Which targets an org owns still comes from the orgs: block above, so an org created this way owns none until an entry there names some. Two orgs may each claim a target of the same name, and each is authorized for it.

Members of several orgs

A GitHub login that the membership above admits to more than one org acts as one of them at a time, and chooses which. Sign-in records every org the login may act as, together with the role it holds in each — an org's editorTeams promotes a member inside that org alone, so the role travels with the tenant — and the web UI header offers them as a dropdown in place of the read-only org badge. One endpoint backs it, and unlike the four above it is not admin-only: it moves the caller between orgs that already admit them, and grants nothing their last sign-in did not already establish.

Request What it does
POST /api/org Make {"org": "<slug>"} the caller's active org, with the role they hold there. Refused with a 403 for any org the caller is not a member of — the same answer a nonexistent slug gets, so the refusal discloses no tenant they may not act as.

The audit log records the move against the destination org, with the origin in the entry's detail. The choice survives later sign-ins: a login that picked an org lands there again rather than being re-resolved to the best match, which is the difference between a choice and a tie-break. It stops surviving only when the org stops admitting the login, and then the next sign-in relocates them exactly as it relocates a login that never picked anything. An admin admitted by one of the Teams in BAJUTSU_OAUTH_ADMIN_TEAMS may act as every live org, including one created after they signed in: no org's membership names them, so a set stored at sign-in would be empty and one stored later would go stale on the next POST /api/orgs.

A membership you revoke through POST /api/orgs/<slug>/membership keeps admitting a switch into that org until the login next signs in — the same next-sign-in latency every membership change already has, and the same one that keeps them acting as the org they are already in. Revoke their sessions if you need it to take effect at once; retiring an org (DELETE /api/orgs/<slug>) already does that for you.

A switch repoints only what the caller does next. A run keeps the org it was enqueued under, all the way to a remote worker, so its evidence and its database row land in the org that started it even if the caller switches while it runs.

Upgrading a database-backed deployment. Run the Alembic migration as usual; it adds columns and seeds nothing. serve itself copies the bound config's orgs: membership into the database on its next start, once per org, so an existing deployment keeps admitting the same people it did before. From then on the file no longer decides those four fields, and serve writes a warning under event=org.membership.ignored (with check=orgs_membership_ignored) naming any org whose entry still declares them. Pare those entries down to targets: at your convenience — that field is still read, and paring before the first copy is as safe as paring after: an entry declaring only targets: is skipped rather than copied, so it is left uncopied for a later config to seed rather than fixed at admitting nobody. Two behaviors change with the cutover, both by design: an unreadable or unbound config no longer denies anyone, because the database alone decides sign-in, and a database serve cannot read answers a sign-in with HTTP 503 naming the store rather than a 403 blaming the user's GitHub membership. That 503 is recorded under its own event=oauth.store_unavailable at WARNING, not under oauth.denied — nobody was turned away, and an alert on a denial should point at your GitHub configuration, never at an outage of the store.

Bootstrapping the first org. A brand-new database has no org, so nobody matches the sign-in gate. A member of a configured BAJUTSU_OAUTH_ADMIN_TEAMS Team clears that gate regardless of how many orgs exist (see Add GitHub OAuth above), signs in as admin, and creates the first one from the Orgs page.

Keeping the Mac pool fair across orgs. Set BAJUTSU_MAX_CONCURRENT_PER_ORG to cap how many runs one org may have in flight at once, so a busy org can't monopolize the scarce devices even when its users each stay under their own BAJUTSU_MAX_CONCURRENT_PER_USER. Both default to unlimited (0), and both sit under the global --max-concurrent-runs; an over-cap request is rejected (HTTP 429) rather than queued. A fan-out (run-set) is the exception: it queues every scenario, and the caps apply when a worker leases a job, so the fan-out runs in turns as slots free (BE-0484). (Fair scheduling across orgs — holding the rejected work in a per-org queue and dispatching it round-robin — is still future work; today the cap rejects a plain run.)

Deleting runs, and how long the trash is kept. A run (and its report) can be deleted through the API (BE-0239): DELETE /api/runs/{id} soft-deletes it — the run drops out of the history list but is moved to a trash and stays restorable via POST /api/runs/{id}/restore; DELETE /api/runs/{id}?purge=true skips the trash and removes the bytes immediately. Soft-delete and restore are editor actions; the immediate purge is admin. POST /api/runs/bulk-delete (body {"ids": [...], "purge": <bool>}) does many at once. A soft-deleted run is purged for good once it has been in the trash longer than the retention window, checked opportunistically on the next history read (there is no background job).

Variable Default Meaning
BAJUTSU_RUN_RETENTION_DAYS 30 Days a soft-deleted run stays in the trash before it is permanently purged. 0 (or less) disables the automatic purge — the trash is then kept until an explicit ?purge=true.

(The Web UI surface for this — a per-row delete affordance and a Trash view — is still to come; the API above is live today.)

Operational logging

The hosted serve emits its own diagnostic trace — structured JSON, written to stdout, with secrets redacted — so you can follow one user action across the control plane and its workers. This trace is separate from the three log surfaces you already have: the test subject's evidence, the live run output stream, and the audit log of who-did-what. Aggregating these lines (shipping stdout to your log stack) is the deployment's job — the tool only produces them.

Two environment variables select the format and verbosity (read once at startup):

Variable Default Meaning
BAJUTSU_LOG_FORMAT json json for the structured serve channel, or text for a human-readable line.
BAJUTSU_LOG_LEVEL INFO Standard level name (DEBUG / INFO / WARNING / ERROR / CRITICAL).

The deterministic run / CI path is unaffected: it never configures this channel, so it stays quiet and stdlib-only.

Correlation. Each JSON line carries the ids that let you trace one action end to end — request_id minted at the request boundary, and job_id / org / actor / run_id bound on the worker — so a control-plane request and the worker run it triggered share the same id values across processes. A line looks like:

{"ts": "2026-06-28T12:00:00+00:00", "level": "INFO", "logger": "bajutsu.serve.operations",
 "event": "run.dispatched", "msg": "job dispatched", "request_id": "…", "org": "acme",
 "job_id": "…"}

The event field names a stable event (run.dispatched, quota.rejected, worker.job.started, worker.job.finished, artifact.upload.failed, server.startup_warning, oauth.login, oauth.denied, …) so you can grep and alert on it. server.startup_warning also carries a check field (e.g. admin_teams_empty) naming which startup condition fired, distinct from the free-text msg — key an alert on check rather than on message text that can reword. oauth.login records every successful sign-in and carries a bypass field, true only when a configured admin Team — not orgs: — is what admitted the login; that field is the only record a bypass admission leaves. Most bypass admissions are INFO, since an admin Team in an operations-only organization bypasses on every sign-in by design; oauth.login is WARNING only when the bypass admitted a login while the org model itself was unusable. Which state that is depends on where the org model comes from: on a deployment whose orgs: block is the source, no config bound, a config that failed to load, or one declaring no orgs: block; on a deployment whose database holds the membership, an orgs table in which no row declares any membership yet — an empty table, but equally one whose rows all carry an empty roster: the passive row a bypass sign-in creates for itself, or orgs an admin created on the Orgs page and has not filled in yet. So alert on WARNING, and grep bypass when auditing who signed in and when.

Redaction is structural. A single filter sits at the root logger, so every line — including ones from third-party libraries — is scrubbed before it is written; correctness does not depend on each call site remembering to mask. It masks known secret values (the operator token, the OAuth client secret, ANTHROPIC_API_KEY, and a run's resolved ${secrets.X} while that run is in flight) and sensitive field names (authorization, token, secret, password, cookie, api_key), replacing them with [REDACTED].

Metrics and observability (BE-0169)

Structured logs (above) are events; metrics are the time series that show whether the pool is saturated, which org is consuming it, whether runs are taking longer than usual, and whether a worker is alive. The control plane exposes them in Prometheus text format at GET /metrics, derived from state it already tracks (the jobs table and lease/heartbeat records) — so it adds no bookkeeping:

Metric Type Meaning
bajutsu_in_flight_jobs{org} gauge Jobs the control plane is running itself, by org (local serve).
bajutsu_queue_depth{org} gauge Jobs waiting in the queue, by org (server backend).
bajutsu_leased_jobs{org} gauge Jobs leased to a worker — in flight — by org (server backend).
bajutsu_worker_heartbeat_age_seconds{worker} gauge Seconds since a worker's last heartbeat; rising past the lease timeout means a dead worker.
bajutsu_oldest_in_flight_seconds gauge Seconds since the oldest in-flight job was enqueued (includes time it waited in the queue) — a slow / stuck-run signal.
bajutsu_unroutable_jobs gauge Queued jobs no live worker can serve — their required capabilities match no worker's advertised set (capability routing). A rising count means "add a worker with the missing capability."
bajutsu_max_concurrent gauge Configured cap on concurrent jobs (0 = unlimited).

/metrics is not a public surface: it sits behind the same auth gate as the rest of serve (BE-0051), so with a token configured a scraper must send Authorization: Bearer <token>. The output carries only counts, ages, and org / worker identifiers — never a job spec, a result, or the token — so a scrape cannot leak a secret. Every server keeps its queue in a database. Every server thus reports the queue, lease, and worker series too.

The compose stack ships an optional Prometheus + Grafana profile (like caddy):

docker compose --profile metrics up -d

Grafana lands on :3000 (admin / GRAFANA_ADMIN_PASSWORD) with the Prometheus datasource and a starter Bajutsu serve dashboard already provisioned; Prometheus scrapes /metrics with BAJUTSU_SERVE_TOKEN. Point a hosted scraper at the endpoint instead if you prefer. Like the rest of the compose stack this profile is verified by hand, not by CI: bring it up, then check Prometheus's bajutsu-serve target is UP and the dashboard charts the series.