shakacode Driving twin-servers from an agent
shaka-perf servers (no subcommand) auto-rebuilds, starts containers, then drops into an interactive menu — that's the path for humans, not agents. As an agent, call the subcommands directly.
The dispatch table is the documentation
| Subcommand | With shaka-perf servers running → proxied |
Without shaka-perf servers → local |
|---|---|---|
build [--target control|experiment] [--no-cache] |
Rebuilds image(s) and restarts the servers (containers re-created — in-container state reset). | Builds the Docker image(s) only; doesn't touch a running session. |
start-containers |
Recreates containers and restarts the servers (state reset). | Brings containers up idle and runs setupCommands on both sides. |
stop-containers |
Stops containers and ends the menu session. | Stops containers and removes volumes. |
prune-cache [--images] |
Queues behind any active lifecycle action, then prunes only this project's isolated Buildx cache; --images also removes its control and experiment images. |
Prunes only this project's isolated Buildx cache; --images also removes its control and experiment images. |
start-servers |
Restarts overmind in the live session (containers untouched). | Launches the app via Overmind in this terminal — blocks; run in background. |
run-cmd <control|experiment> <cmd> |
Same as local — docker execs into the named side (queued behind any in-flight lifecycle work). |
Runs a one-off command inside the named side via docker exec. |
run-cmd-parallel <cmd> |
Same as local — docker execs into both sides in parallel (queued behind lifecycle work). |
Runs the same command in both containers in parallel. |
sync-changes <control|experiment> |
Fails — the menu's fs.watch already auto-syncs the build context on every save; re-running would race the watcher. Just edit your files. |
Syncs local git changes into the side's bind-mount volume. |
get-config <key> |
Local — pure read; the value belongs on the caller's stdout. | Reads a resolved config field (e.g. dockerfile, ports). |
say <message> |
Local. | Speaks the message via TTS (macOS/Linux). |
notify-server-started <control|experiment> |
Local — Procfile helper. | Waits for the side's URL to respond, announces it via TTS, then sleeps to keep Overmind happy. |
run-overmind-command <control|experiment> <cmd> |
Local — Procfile helper. | Runs a command inside a container with PID tracking (used inside Procfile lines). |
copy-changes-to-ssh <port> <host> [control|experiment|all] |
Local. | Copies local git changes to a CI SSH host for debugging. |
forward-ports <port> <host> [controlPort] [experimentPort] |
Local. | Forwards CI container ports to localhost via SSH. |
customize-docker-compose |
Local. | Copies the bundled docker-compose.yml into the project for local editing. |
Lifecycle from cold start (no menu): build → start-containers → start-servers. Inside a running menu, the proxied versions of build / start-containers already include the restart step.
Each project builds through an auto-created docker-container Buildx builder
derived from its project slug. Control and experiment share that builder, while
other projects use different builders. Use prune-cache for project-scoped
cleanup; add --images only when the loaded control and experiment images
should be removed too.
Behaviour with shaka-perf servers running
The proxied work runs inside the menu's process, so its logs land in the user's interactive window and you just see the exit code on stderr after a → proxying to running shaka-perf servers (pid …) notice.
- If another action is already in flight (menu item or earlier proxied command), your subcommand queues on the menu's session lock and the client just hangs until the slot opens — no fast-fail.
- Exit code
75(EX_TEMPFAIL) is reserved for terminal states only: the menu is shutting down, or hadn't finished booting yet — try again in a moment. - To change the running servers' environment (env vars, config file), ask the user to kill the interactive
shaka-perf serversso your direct subcommands can take over.