Oko
Oko/Docs

Command reference

oko sessions start

Starts a new agent session, or any executable, in a new broker-owned terminal session.

Invocation#

Command
oko sessions start --text TEXT [--harness NAME] [--model PROVIDER/MODEL] [--cwd DIR] [--socket PATH] [--json]; oko sessions start --executable PATH [--runtime NAME] [--cwd DIR] [--socket PATH] [-- ARG...]

Inputs and options#

  • Without --executable, a new session of --harness: Jeden unless another is named (OMP starts only with `--harness omp`). --text is its first prompt and --cwd its directory. An explicit --model is passed to the harness; a declared name such as `sol` resolves to OMP's most recently used matching provider/model identity in model_usage. Without --model OMP selects a declared model with an enabled account whose latest applicable usage windows report free capacity, favoring the least-used measured account and then the fewest live sessions. Every OMP selector comes from model_usage, not a pinned vendor alias. Jeden uses the declared mix and Brama's model catalog. The executable and start arguments are declared in runtimes.json.
  • With --executable, --cwd selects the working directory and arguments follow --. Other programs start as given. For `--executable omp`, Oko adds --model from the measured declared mix when the child arguments name none, and uses the same leased or measured-account start as `--harness omp`. An explicit child --model is preserved without reading the live agent and delivery inventory; when Brama refuses a lease, that model still needs a usable measured OMP account. --runtime selects a declared agent runtime for other executable starts; a --runtime after -- belongs to the child, not Oko.

Output and state effect#

  • An agent session is answered once its harness writes the first prompt in its transcript. The result prints session, transcript, broker terminal id, processIdentifier, executable, harness, selected model, workingDirectory, socket, spawnedAt, attach and unleased when applicable. An OAuth account is pinned through OMP's auth broker; a sole measured API key uses OMP's store directly; Jeden uses Brama's proxy. When Brama refuses a lease with HTTP 403 or cannot be asked, OMP instead runs on its own enabled account with measured free usage. The unleased result names Brama's refusal, provider, selected model and account, measurement and running count; the human output names the refusal and chosen model. `oko sessions agents` reads the actual provider and model from the transcript. A broker too old for leased starts refuses `unknown command: spawn-leased`.
  • An executable prints the broker's record: id, processIdentifier, executable, workingDirectory, attachSocketPath and createdAt. OMP also prints the selected model and any unleased Brama cause and account; it does not silently start on OMP's default.
  • The child starts with an unblocked signal mask, including SIGCHLD, SIGINT, and SIGTERM. The same launch path serves CLI sessions, Desktop terminals, and task-control workers.

Refusals and safe exits#

  • “oko sessions start requires --text <text>”, “oko sessions start --text takes the session's first prompt; it was empty”, “oko sessions start: --harness takes a value; write --harness <text>” and “oko sessions start does not take <flag>; it takes --harness, --model, --text, --cwd, --socket” for an agent session; “oko sessions start requires --runtime <text>” for an executable (exit 2).
  • “oko sessions start: --cwd <dir> is not a directory on this machine”, “<harness> sessions cannot be started by this machine: runtimes.json declares how to start jeden, omp only” and “no agent runtime to start the session with: <harness> is not installed at any declared path (<paths>)” (exit 1).
  • “the new <harness> session was not started: <executable>, broker <terminal>, pid <pid> (not running): no transcript holding the first prompt was observed after <n>s; terminal output: …” when the harness ended before writing its transcript (exit 1).
  • An unsupported runtime, a full subscription pool, an incomplete routing overlay or failed executable launch preserves its refusal. Jeden never starts without Brama. OMP refuses when its usage database cannot be read, no enabled account has measured free usage, or a declared provider has no model recorded by OMP; a Brama refusal is not silently treated as a lease. If the unleased-session inventory cannot be written after spawn, Oko ends that terminal and names the accounting failure; if ending it also fails, it names both causes and warns that the terminal may still run.

CLI reference#