# Supervisor

> Branch-scoped notes for the public experimental supervisor work.

Canonical: https://loxa.dev/docs/experimental/supervisor

Maturity: Experimental

Experimental · feature/supervisor at 14daf02

This page describes public branch-scoped work at
[`feature/supervisor` commit `14daf02`](https://github.com/loxadev/loxa/tree/14daf02).
It is not part of `origin/main` or a tagged release.

## Prerequisites [#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>]` [#run-id---ctx-u32---port-u16]

```text
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` [#ps]

```text
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>` [#stop-target]

```text
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 [#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](/docs/cli), [Models](/docs/models), or
[Project status](/docs/project) for non-experimental documentation.