Headless and server

oceancode runs without a UI two ways: a one-shot run for scripts and CI, and a long-lived serve that exposes the engine's HTTP surface to clients. The terminal UI is Ocean pager, which embeds the engine in its own process (see 19 · Ocean pager); serve is the headless surface.

One-shot — oceancode run

Run a single non-interactive turn and exit.

oceancode run "explain what this repo does"
oceancode run --format json "fix the failing test"
oceancode run --continue "and now add a test for it"

Flags go before the prompt (a flag after it is sent to the model as text, with a warning). When stdin is not a terminal, run reads it to EOF and appends it to the prompt — the piped body is the instruction — so a script that passes the prompt as an argument must close stdin (oceancode run "hi" </dev/null) or the run waits forever (observed 2026-10-05: four minutes of nothing with stdin left open).

Useful flags:

Bound flags (--max-usd, --max-minutes, --max-steps, --tideline, --subagent) must come before the prompt — the parser stops at the first non-flag word, and a bound placed after the prompt is ignored with a warning. --tideline <pct>% sets the tideline as a share of the model's context (e.g. --tideline 50%); --tideline <limit> or default also work. The floor and the presets were removed: a second number or a preset word is refused with the usage line. The old --window name is refused with the hint use --tideline; --shelve still works as an alias. See 08 · Bounding a long run.

The engine also serves GET /session/{id}/subagent → {"model": <ModelRef> | null} — the session's effective sub-agent model (the /subagent override, else the fleet router's CLAUDE_CODE_SUBAGENT_MODEL while the subscription slot is live, else the subagent.model config, else the session's own model). A client reads it for the identity row's sub-agents <name> segment; an engine without the route answers as "nothing to show".

Host-run workflows — oceancode workflow

Launch and control a host-run Rhai workflow without a UI. workflow run boots the engine the same way oceancode run does, launches the workflow, streams each workflow_updated body as one JSON line on stdout, and exits by the run's outcome.

oceancode workflow run pipeline --args '{"steps":[{"prompt":"say A"},{"prompt":"say B"}]}'
oceancode workflow run ./research.rhai --budget 64 --model openai/gpt-5-mini
oceancode workflow run pipeline --validate-only --args '{"steps":[{"prompt":"x"}]}'
oceancode workflow runs --all
oceancode workflow stop wf-…

The workflow name (or a path to a .rhai file) comes first, before any flags. A registered name (a built-in such as pipeline, or a discovered .oceancode/workflows/<name>.rhai) is resolved by the launcher; a path you type is read and run as an inline script.

Exit codes (the run's outcome): 0 complete; 2 failed, cancelled or budget_limited; 3 a pause (user_paused, back_off_paused, no_progress_paused, infra_paused, blocked). The last streamed line always carries the terminating body, so a script can read the outcome from stdout as well as from $?.

workflow runs [--all] lists the persisted runs (each workflow_updated body, one per line), read from the run directories under the app data dir — scoped to the current project unless --all lifts the filter. workflow pause|resume|stop <run_id> drive the launcher's control seam; resume takes an optional --budget <n> to lift a budget-limited run. These control a run live in the engine this command boots — a run launched by a separate oceancode workflow run has already exited in its own process, so cross-process control is a shared-server concern not wired here.

Goal mode — oceancode goal

Prove an objective is done, not merely claim it — headless. oceancode goal "<objective>" boots the engine like oceancode run does, launches the built-in goal workflow (Plan → Work → Verify: plan the objective into verifiable deliverables, work in rounds with one resumed worker, and converge only when a cold panel of adversarial skeptics fails to refute completion), streams each goal_updated body as one JSON line on stdout, and exits by the run's outcome. It is the headless twin of the pager's orchestrate: always goal mode (19-pager.md).

oceancode goal "add a --json flag to the status command and prove it works"
oceancode goal --budget 64 --model openai/gpt-5-mini "port the parser to the new API"

The objective is the positional argument — quote it, or let the words after the flags form it. Go-style flag parsing stops at the first positional, so any flag must come before the objective.

Exit codes (the run's outcome): 0 complete; 2 failed, interrupted (a stopped run) or budget_limited; 3 a pause (user_paused, back_off_paused, no_progress_paused, infra_paused, blocked) — a goal that stalls on identical gaps two rounds running, or spends its budget, pauses rather than looping forever. The last streamed line always carries the terminating body, so the outcome reads from stdout as well as from $?. A finished goal is also listed by oceancode workflow runs --all (it shares the workflow run store).

Long-lived server — oceancode serve

oceancode serve                 # loopback, port 4096
oceancode serve --port 8080

The default shape (oceancode, the pager) passes --listen <host:port> through to the engine it embeds; a non-loopback bind refuses to start without a server password (below). The guard is enforced inside the server for both oceancode --listen and oceancode serve --host.

Authentication

HTTP basic auth is off until you set a password.

A non-loopback bind (--listen on the default shape, or serving to a public interface) refuses to start unless OC_SERVER_PASSWORD is set.

Managing capabilities from the CLI

Besides run and serve, the binary answers a set of non-interactive management subcommands that boot no session. Each is read-only or writes a single config file, and exits.

Every management subcommand takes --dir <d> (the project; default: the current directory) and --home <h> (the home the user tier and ~/.oceancode are read from; default: your home) so a script — or a test — can point it at another tree.

Permission mode

A client reads and switches the session's permission mode over HTTP — the boot default is the permission_mode config key, and these two routes change it live (the pager switches it from its own prompt):

The four modes are default, acceptEdits, dontAsk, bypassPermissions — see 12 · Permissions and sandbox.

Managed (enterprise) configuration

For a shared or locked-down deployment, an administrator layers a managed config and a signed requirements file over every project:

• OC_MANAGED_CONFIG — path to the managed config file (default: the OS admin path). It is loaded last, so it overrides the project and global files.
• OC_REQUIREMENTS_PUBKEY — the trusted ed25519 public key (64 hex chars) that a requirements.json signature is checked against; an unsigned or tampered file is refused. With no key set, managed requirements are not enforced.

Both are described in 02 · Configuration; the requirements file can disable bypassPermissions, allow-list MCP servers, and pin config keys. See 12 · Permissions and sandbox.

See also

• 01 · Getting started — the three boot shapes.
• 02 · Configuration — the server variables in one table.