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 serveand a localbajutsu workerthat 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 aLaunchDaemon. - 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 servedirectly, so — unlikemake serve— it does not install them on demand. Install the backend's runtime closure — the single extra that names everything a run reaches, including thevisual(screenshot) andschema(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 suppliesxcodebuild, and the target supplies its prebuiltdriver.runner.testRunner— soworker-iosis just thevisual+schemaassertion 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 withno 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) withRunAtLoad+KeepAlive; - puts the token in
EnvironmentVariables(BAJUTSU_SERVE_TOKEN) — never in the argv, so it isn't visible inps; - 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, setBAJUTSU_AI_PROVIDER/BAJUTSU_BEDROCK_MODELand the AWS credentials here instead.)PATH— for the iOS (XCUITest) backend only. launchd starts the agent with a minimalPATH, and bajutsu locatesxcodebuild/xcrun/simctlthroughPATH, so without it a run fails withno available actuator. Include the Xcode command-line tools' bin, Homebrew's bin, and the venv's bin. (The web backend finds Playwright by import, notPATH, so it needs noPATHentry.)
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:
- Copy the plist under another label.
- Change its
ProgramArgumentstopython -m bajutsu worker --platform ios. Append--server-state-dir <project>/.bajutsu, where<project>holds the server's runs directory.--server-state-dirlets 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. - Put the same token in its
EnvironmentVariables, asBAJUTSU_TOKEN. - 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.
3. Expose it over Tailscale (recommended)¶
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.0to the public internet. Even with a token, the safe default is a private tailnet. serve refuses a non-loopback--hostwithout 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 theservehost. The bundle declares its runtime with exactly one ofdockerImage(a published base image, e.g.node:20-slim) ordockerfile(a bundle-relative path thatservebuilds withdocker build), plus aport(the in-container listen port). The container is hardened —--rm, all capabilities dropped, no new privileges, a read-only root filesystem with atmpfsscratch, 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 theservehost.reuse— never run the uploaded command; only probe an operator-provisioned server already answering atsubject.url. If nothing answers, the run fails loud rather than starting anything.deny— refuse the uploaded command outright; likereuse, 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):
- a configured GitHub App installation (recommended for an unattended host — see below);
- a credential entered via the web UI's "From a Git repository" dialog (held in
BAJUTSU_GIT_CONFIG_TOKEN— see below); GITHUB_TOKEN/GH_TOKENfrom the environment;gh auth token, for a developer with an interactiveghsession on their own machine;- 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.
GitHub App (recommended for a service)¶
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).
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
hostedis 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 itspaths.scenarios/paths.baselines/subject.pathare 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.deletedmarker. 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 setsdeleted_atinstead 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
serveprocess 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 answers404. 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 localbajutsu serve --asgiand 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/recorddispatches 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.buildnever 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'sbundle_urlsfield 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 resolvessubject.pathfrom the bound config and, if it's missing, runs the config'ssubject.buildcommand; 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 itssubject.buildsuppressed 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, arecord, or acrawl
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 arecordjob 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
noticefield of the job view,GET /api/jobs/<id>; - a
noticeevent 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:
artifactsbaselinesscenariosuploads
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 a400that claims the upload never happened. - With
scenariosArtifact,servelooks upscenarioamong 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. serverefuses a single YAML Ain't Markup Language (YAML) file. A digest carries no file name to matchscenarioagainst.binaryArtifacton a target with nosubject.path, such as a web target, returns400.- A single-process
serverefuses both fields. It runs the job in the operator's own project directory, which no override may overwrite. POST /api/run-setrefuses 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
membersentry, a member of agithubOrgs-listed GitHub org, or a direct member of agithubTeams-listed oreditorTeams-listed GitHub Team (seeorgs:) — and a successful sign-in grants viewer (read-only).githubTeamsis 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/teamsfails 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 anorgs: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 sameorgs: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.editorTeamsadmits as well as promotes, so a Team named there needs no second entry undergithubTeamsto 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 singulareditorTeamstill works:servefolds that key intoeditorTeams. 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; likegithubTeamsandeditorTeams, 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'smembers,githubOrgs,githubTeams, oreditorTeams— so an admin can sign in and repoint the server at a corrected config even when theorgs:block is broken or missing entirely. One failure still closes that door:/user/teamsfails 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_TEAMSis 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 byenvironmentwhen 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: writeby default. Apull_request_targetworkflow 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 byenvironmentso 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.logwhen it exists. - A viewer who watched live gets
console.logat 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_URLon every replica, for exampleredis://cache:6379/0. - Install the
redispackage 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. Arunjob 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 jobcancelled. - 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
--platformand from the machine itself. The--platformvalue gives the backend axis:platform:iosfor a Mac iOS worker,platform:webfor the Playwright container. Every worker advertiseshost:<os>for the operating system it runs on, such ashost:darwinon a Mac (BE-0450). An iOS worker also advertises its installed Simulator inventory. That inventory gives aniosNNtoken per runtime, and theiphoneandipaddevice classes. An iOS worker also advertisesdevice:iphoneanddevice:ipadfor the families of the real devices connected to it, read overdevicectl. 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 advertisesmachine:<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 advertisesweband 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 advertiseskind:simulatorwhen its inventory holds an iPhone or iPad Simulator. It advertiseskind:devicewhile it reads a real iPhone or iPad overdevicectl. A worker capability file that setsrealDevices: falseturns that token off. A Device Farm worker advertisesplatform:android,platform:ios, andkind: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
--platformagainst 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 iosthus stops withxcuitest 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 thefakebackend 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
platformdecides its driver. When that driver runs on one operating system alone, the set also holdshost:<os>. An iOS target on thexcuitestdriver thus requireshost:darwin. A web or Android target adds nohost: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, sincerequires:anddefaults.requiresare gone (BE-0452). Routing derives noios18token fromrunsOn.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'srunsOn.ios.kindlists. One worker thus needs a fitting device for each. A Simulator run requires the inventory'siphoneoripadtoken. A real-device run requires thedevice:one. A single family requires its token, sokind: devicewithfamily: ipadrequiresdevice: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 thefakedriver adds none either, because that driver drives no device (BE-0468). - A fan-out job requires no placement. A job of
POST /api/run-setrequires its target'splatform:<p>,job:run-intent, and thecap:andsetting:tokens of its scenario's route (below). An iOS job adds the family tokens above and onekind:<kind>token per kind its runs take. It requires nohost:,environment:, ormachine: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 namingrunsOn.ios.familynever routes there. A worker that advertises anenvironment: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.
devicectllists every paired real device, plugged in or not. Its tunnel state readsdisconnecteduntil 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, orweb. 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 underrunsOn.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 onxcuitestnow requireshost: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 risingbajutsu_unroutable_jobs. Roll the worker binaries first (or together), not after. The same order holds for BE-0449: the control plane now queues arunaspython -m bajutsu.run.internal, which a worker built before that change cannot map onto its own interpreter, so such a worker fails everyrunit leases.BE-0467 goes the other way. A worker built before it advertises no
cap:orsetting:token, and the control plane matches such a worker on the other tokens alone, so an upgrade never strands a queue. The lease recordsworkerRouting: uncheckedon each such job's provenance, which reaches the run'smanifest.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 noplatform:token. In both cases the fan-out jobs stay queued and count towardbajutsu_unroutable_jobs. A worker started with--capabilities platform:…orkind:…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.