For AI agents: an index of this guide is available at https://www.plungeai.com/guide/llms.txt. Append .md to any page URL, or send Accept: text/markdown, to get markdown. The developer documentation is at https://www.plungeai.com/docs/llms.txt.

Documentation Index: fetch the complete documentation index at /llms.txt. Use this file to discover all available pages before exploring further.
Feedback

oceancode ships in two builds. The default build is the standalone coding agent and contains no platform code at all. The platform build is produced with

cargo build --release -p ocean-cli --features platform

and adds the three PlungeAI couplings: the OceanTunnel daemon (crates/ocean-app/src/oceantunnel.rs), the enrich resolver (crates/ocean-agent/src/systemcontext/remote.rs) and the per-step remote capability packs (crates/ocean-agent/src/systemcontext/capability.rs). Everything the ocean config section describes below is inert in the default build.

The platform cargo feature is declared on three crates — ocean-agent, ocean-app and ocean-cli — and is off by default. The OceanInfo schema itself (every ocean.* key) stays in the leaf crate ocean-config in both builds, so an oceancode.json with an ocean section parses either way; only the code that acts on it is gated.

Which build do I have?

node scripts/gates/check-platform-boundary.mjs --no-build scans the two release binaries for three byte-literal markers after a release build and reports markers_local=0 markers_platform=3 when the boundary holds; a routine ./check.sh proves the same boundary on debug builds (--debug, which builds target/debug/oceancode under both feature sets and scans between the builds — no release build needed). At runtime, oceancode inspect reports a platform row: compiled in on a platform build, not compiled in on the default build.

The "platform: not compiled in" notice

A default build that finds ocean.mode = "platform" or a non-empty ocean.endpoint in oceancode.json prints once at boot and in oceancode inspect:

platform: not compiled in (ocean.mode or ocean.endpoint is set; rebuild with --features platform)

It is a single warning, not an error: the agent still runs, exactly as it does for any user with no ocean section. Rebuild with --features platform to make the section take effect. A config without an ocean section prints nothing.

Config keys

The ocean.* keys are serde-only and present in both builds; they take effect only in the platform build (crates/ocean-config/src/ocean.rs:15-88).

KeyMeaningDefault
modelocal or platform. The only switch that selects platform behaviour.local
endpointEnrich URL (GET ?agent=<name>&directory=<dir> → {baseline, version}).empty
headersHeaders sent on every platform request (auth lives here).none
ttl_secondsHow often a session re-checks the enrich endpoint (0 → 300).300
agentsPlatform-resolved agent names; empty defaults to ocean-build, ocean-plan.ocean-build, ocean-plan
mcp_urlAuto-registers the platform MCP gateway as a remote MCP server named ocean.empty
capability_endpointPer-step capability pack endpoint.empty
gateway_base_urlThe inference gateway a provider baseURL should point at: the bare host or its /v1 root, both work.https://api.plungeai.com/v1 in platform mode
tunnel_urlOceanTunnel dial-out URL; with a token, runs the tunnel daemon.empty
tunnel_tokenInline OceanTunnel session token.empty
tunnel_token_fileFile holding the tunnel token (~/ expands against $HOME).empty
tunnel_agentLocal agent name registered with the tunnel.oceancode

The switch is config-only. No environment variable selects platform mode; ocean.mode in oceancode.json is the only switch — there is no OCEANCODE_MODE / OC_MODE. Two platform-related environment variables the binary reads never turn platform mode on by themselves:

  • OC_TUNNEL_TOKEN — the tunnel session token, read at the highest priority (above the deprecated OCEAN_TUNNEL_TOKEN, then tunnel_token_file, then the inline tunnel_token). OCEAN_TUNNEL_TOKEN is still read as a legacy fallback and logs one deprecation warning per process.
  • OC_SSO_TOKEN — a per-request gateway SSO session token. When set, oceancode attaches it as the X-Ocean-SSO-Token header (no Bearer prefix) on requests to the configured https gateway host only — never a direct-provider host, never over plaintext — and never on Authorization (the wallet bearer, your ozk_ key, stays intact). Read at runtime, never persisted. Server-side reader is a pending platform handoff: until the inference gateway reads X-Ocean-SSO-Token, the header is ignored (harmless).

Every variable also has a row in 02 · Configuration.

Per-step capabilities

In platform mode the local <available_skills> catalog is replaced by a capability pack sized to the plan row the model is working. At each step boundary the resolver asks the capability endpoint for a pack (eager skill bodies within a 24 KiB budget, a deferred index, and a version); 304 when the pack is unchanged, so the retained prefix — and the provider's prompt cache — never changes because a skill changed. Deferred bodies cost nothing until pulled:

  • load_capability tool — a platform-build tool that pulls a deferred capability body by id (load_capability {id}) into the transcript as a normal tool result, never a file on disk. It is registered only in the platform build and refuses any id the platform never offered.
  • capability permission — the permission family that governs load_capability. It asks by default in the read-only agent families (ask, explore, security-review) and is allowed for the build, plan and general families.
  • Registry skills — platform mode can also discover skills straight from the registry with no local files; they surface with the provenance platform:<id> (tier platform, bound tool id skill_platform_<id>) and load with no base-directory line.

Model routing and the wallet

Signing in. On a platform build, oceancode login --provider ocean (alias plungeai) signs you in to your PlungeAI account through the browser with OAuth 2.1 and PKCE, as the first-party client oceancode of https://signin.plungeai.com. oceancode listens on a loopback port, opens the authorize page (you sign in with any method auth.plungeai.com offers, if you are not signed in already), takes the redirect back to http://127.0.0.1:<port>/callback, checks its state and trades the one-time code with its PKCE verifier. The refresh token goes to the macOS keychain, item plungeai / account oceancode (on other systems into auth.json, mode 0600); auth.json gets only a marker under ocean ({"type":"oauth","enterpriseUrl":"https://signin.plungeai.com"}), never the token. Platform mode then fetches a 10-minute access token when it starts, keeps it in memory and refreshes it at 80 % of its life; each refresh rotates the refresh token and writes the new one back to the keychain, so several oceancode processes share one sign-in: a refresh holds signin.lock in the data directory from reading the refresh token to writing the rotated one, so two windows starting together refresh once and neither signs the other out (0.8.8.69; nothing is fetched at boot). Model calls through the gateway (ocean/<provider>/<model>) work on the sign-in alone and are billed to your account's wallet. No token, code or verifier is printed or put on a command line. --no-browser prints the link without opening it; the sign-in gives up after three minutes. oceancode login --provider ocean --key keeps the older sign-in: the dashboard's https://dashboard.plungeai.com/api/cli/authorize page hands back your ozk_ account key, stored in auth.json under ocean (the entry oceancode key ocean writes). oceancode logout ocean revokes the sign-in at signin.plungeai.com first, then deletes the keychain item and the auth.json entry (if the revoke fails, nothing is removed); with only an ozk_ key stored, it removes the key. oceancode base still needs an ozk_ key: with only the sign-in it answers "no Ocean API key".

With an ozk_ platform key stored — oceancode key ocean ozk_… (it lands in auth.json), or a credential under the ocean integration — platform mode synthesizes an ocean provider whose baseURL is the gateway's /v1 root (https://api.plungeai.com/v1 unless gateway_base_url says otherwise), so every model call routes through the inference gateway. A legacy sk-ocean- key is found the same way; when both are stored the ozk_ key wins. A model of auto is resolved once per session from the gateway's /v1/discovery/recommend (falling back to anthropic/claude-sonnet-5-5 if the recommend call fails). The run --format json result envelope then carries two extra objects for a platform-routed run: platform: { fallback_steps } (how many steps failed open to the local route) and wallet: { balance, spent } (present only when the gateway meters). A local run omits both.

The ledger in platform mode

Two engine-owned sections in SESSION.md are fed by platform-mode durable events:

  • ## Plan changes by user — regenerated from todo.updated events, one summary line per event that carried user-authored plan rows (the model's own edits contribute nothing).
  • ## Capabilities used — regenerated from pack.manifest events, one | step | ids | version | hash | row per step; a fallback step lists its row with an empty id cell.

Both are bounded to the newest 20 rows and regenerated on every write, so they never crowd out model-owned sections. Plan rows also carry cross-session history: when a row that completed or was cancelled in an earlier session reappears, its projection shows how often it was seen and how often it failed.