Supervisor

Experimental · feature/supervisor at 14daf02

This page describes public branch-scoped work at feature/supervisor commit 14daf02. It is not part of origin/main or a tagged release.

Prerequisites

The selected registry model must already be downloaded under ~/.loxa/models. The branch also requires a llama-server executable.

Set LOXA_LLAMA_SERVER to a llama-server file path, or make llama-server discoverable on PATH. If the environment path is empty or does not name a file, the branch continues with PATH discovery.

run <id> [--ctx <u32>] [--port <u16>]

loxa run <id> [--ctx <u32>] [--port <u16>]

id must be a registry ID whose final model file is present. --ctx accepts a u32 context size and defaults to 8,192. --port accepts a u16 port. When no port is provided, the branch asks the operating system for an available local port.

The spawned server binds to 127.0.0.1. Startup readiness first checks /health. It falls back to /v1/models only when /health responds with 404, 405, or 501. Startup times out after 60 seconds.

When ready, the command reports the model ID, child PID, port, model path, and local health URL. The branch supports one managed run at a time.

After a confirmed unexpected child exit, generation zero is retried once as generation one. A second unexpected exit is not retried. If teardown cannot be confirmed, the branch reports recovery required instead of advancing the managed state.

ps

loxa ps

ps reads ~/.loxa/run/managed.json and reports the active model ID, child PID, port, status, and a model column. Status can be running, stale (identity), stale (pid dead), stale (port dead), or stale (pid dead, port dead).

In this branch revision, the runtime-state record does not retain the model path used to reconstruct a ps row. The model column is therefore currently blank.

stale means the saved child identity, PID reachability, or port reachability no longer agrees with an active managed child. Corrupt or legacy state is reported separately rather than treated as a running sidecar.

stop <target>

loxa stop <target>

target must be the active model ID or all. The command records a stop request and waits for the owner to finish. If the owner identity cannot be confirmed, or the owner does not finish within the branch's bounded wait, the command reports recovery required.

State and logs

Managed state is stored at ~/.loxa/run/managed.json. Server logs are stored under ~/.loxa/run/logs.

Return to the main-branch CLI reference, Models, or Project status for non-experimental documentation.