Skip to content
Back to search

okto-nexus

Local-first MCP coordination hub for multi-agent teams, with durable messaging, handoffs, governance, and observability.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/OktoLabsAI/okto-nexus with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/OktoLabsAI/okto-nexus'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oktolabsai--okto-nexus/badge.svg)](/listings/oktolabsai--okto-nexus)

HTML

<a href="/listings/oktolabsai--okto-nexus"><img src="/api/listings/oktolabsai--okto-nexus/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The recommended install includes the HTTP hub, dashboard, local embedding provider, and tokenizer:

uv tool install "okto-nexus[serve]"
okto-nexus serve

Equivalent with pipx:

pipx install "okto-nexus[serve]"

Available extras:

| Extra | Includes | Use it when | |---|---|---| | none | CLI and coordination library | You are embedding Nexus components | | `serve-lite` | FastAPI, Uvicorn, Core, dashboard | You need HTTP without Torch/model dependencies | | `embeddings` | sentence-transformers | You want the local embedding provider separately | | `serve` | HTTP stack, Core, embeddings, tokenizer | You want the complete supported hub | | `dev` | pytest, FastAPI, Uvicorn, httpx | You are developing or testing Nexus |

The published wheel and sdist contain the compiled dashboard. Node.js is only needed when rebuilding the frontend from source.

From a checkout:

git clone https://github.com/OktoLabsAI/okto-nexus.git
cd okto-nexus
uv sync --extra dev

# Complete HTTP build:
uv sync --extra serve --extra dev

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,494 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Okto Nexus
  2. **Local-first coordination for teams of AI agents.**
  3. Okto Nexus is an MCP server and operator hub for agents working in the same
  4. repository. It gives them durable identities, presence, messages, inboxes,
  5. handoffs, artifacts, an event log, governance controls, and a live dashboard
  6. without requiring a cloud broker.
  7. `okto-nexus serve` exposes the complete hub on one port:
  8. - `/mcp` — MCP over streamable HTTP, authenticated as an agent;
  9. - `/api/v1` — operator REST APIs, read-only monitor endpoints, and SSE;
  10. - `/` — the bundled React dashboard.
  11. MCP is available through HTTP. Coordination records live in one
  12. SQLite database in WAL mode. Optional metrics, referenced workspace files, and
  13. the derived `shared.md` view live outside that database.
  14. | Release fact | Value |
  15. |---|---|
  16. | Package | `okto-nexus 0.3.0` (development) |
  17. | Python | `>=3.11` |
  18. | MCP surface | Use `tools/list` for the active feature configuration |
  19. | MCP resources | 12 versioned reference resources |
  20. | MCP prompts | 0 |
  21. | Surface revision | 62 |
  22. | Database schema | Read the installed revision through `nexus_info` |
  23. | Storage | local SQLite/WAL catalog + adapter-backed artifact payloads |
  24. - PyPI: [pypi.org/project/okto-nexus](https://pypi.org/project/okto-nexus/)
  25. - Source: [github.com/OktoLabsAI/okto-nexus](https://github.com/OktoLabsAI/okto-nexus)
  26. ## Contents
  27. - [Why Nexus](#why-nexus)
  28. - [Install](#install)
  29. - [Start the hub](#start-the-hub)
  30. - [Connect an MCP client](#connect-an-mcp-client)
  31. - [Agent pre-flight](#agent-pre-flight)
  32. - [Architecture](#architecture)
  33. - [HTTP surfaces and authentication](#http-surfaces-and-authentication)
  34. - [Dashboard](#dashboard)
  35. - [Coordination model](#coordination-model)
  36. - [MCP surface](#mcp-surface)
  37. - [Configuration](#configuration)
  38. - [Operations](#operations)
  39. - [Data model and migrations](#data-model-and-migrations)
  40. - [Errors](#errors)
  41. - [Development](#development)
  42. - [Contributing](#contributing)
  43. - [Troubleshooting](#troubleshooting)
  44. - [Security and limitations](#security-and-limitations)
  45. - [Release notes](#release-notes)
  46. - [License](#license)
  47. ## Why Nexus
  48. - **One coordination space per project.** An absolute `project_root` is
  49. canonicalized and hashed into a deterministic `workspace_id`. Every client
  50. that resolves the same real path joins the same workspace.
  51. - **Durable delivery.** Messages fan out into per-recipient inbox lanes with
  52. leases, redelivery, acknowledgements, delivery status, and optional read
  53. receipts.
  54. - **Single-winner work dispatch.** Handoffs support atomic claim, leases,
  55. rejection, cancellation, optional verification, and optional dependency
  56. graphs.
  57. - **Explicit identity and presence.** Operators create identities and API keys;
  58. agents open sessions and heartbeat to remain present.
  59. - **Targeted routing.** Direct, capability, role, tag, broadcast, mixed, and
  60. direct-with-fallback strategies share one validated grammar.
  61. - **Governed communication.** Permissions, communication scopes, versioned
  62. policies, quotas, guardrails, groups, and human approval can restrict writes
  63. without exposing the control plane to agents.
  64. - **Observable by design.** Monotonic event IDs, cursor reads, long-poll,
  65. replay export, SSE, health aggregates, and a live dashboard expose what the
  66. team is doing.
  67. - **Local-first and fail-closed.** Configuration, target grammars, catalogs,
  68. workspace paths, API keys, and state transitions are validated before writes.
  69. - **Token-aware MCP docs.** First-use guidance remains resident; deeper
  70. reference material is available through versioned MCP resources on demand.
  71. ## R4 execution status
  72. For current local and remote execution setup, use the
  73. [R4 operations guide](docs/harness-integrations/r4-operations.md). Nexus embeds
  74. Core locally; the Connector application is required only on remote execution
  75. hosts. Agents connect directly to HTTP `/mcp`. Legacy native launch factories
  76. and Nexus MCP stdio have been retired.
  77. This is a development release. Four adapter catalog entries do not establish
  78. four qualified native integrations. The [acceptance ledger](plans/r4_execution/acceptance_inventory.json)
  79. and [evidence index](docs/harness-integrations/evidence-index.md) distinguish
  80. installed contract tests from final provider/platform/multi-host qualification.
  81. Final G0–G3 acceptance remains open.
  82. ## Install
  83. The recommended install includes the HTTP hub, dashboard, local embedding
  84. provider, and tokenizer:
  85. ```bash
  86. uv tool install "okto-nexus[serve]"
  87. okto-nexus serve
  88. ```
  89. Equivalent with pipx:
  90. ```bash
  91. pipx install "okto-nexus[serve]"
  92. ```
  93. Available extras:
  94. | Extra | Includes | Use it when |
  95. |---|---|---|
  96. | none | CLI and coordination library | You are embedding Nexus components |
  97. | `serve-lite` | FastAPI, Uvicorn, Core, dashboard | You need HTTP without Torch/model dependencies |
  98. | `embeddings` | sentence-transformers | You want the local embedding provider separately |
  99. | `serve` | HTTP stack, Core, embeddings, tokenizer | You want the complete supported hub |
  100. | `dev` | pytest, FastAPI, Uvicorn, httpx | You are developing or testing Nexus |
  101. The published wheel and sdist contain the compiled dashboard. Node.js is only
  102. needed when rebuilding the frontend from source.
  103. From a checkout:
  104. ```bash
  105. git clone https://github.com/OktoLabsAI/okto-nexus.git
  106. cd okto-nexus
  107. uv sync --extra dev
  108. # Complete HTTP build:
  109. uv sync --extra serve --extra dev
  110. ```
  111. ## Start the hub
  112. ```bash
  113. okto-nexus serve
  114. ```
  115. Defaults:
  116. - listen address: `0.0.0.0:8202` (all IPv4 interfaces);
  117. - dashboard: `http://127.0.0.1:8202/`;
  118. - MCP: `http://127.0.0.1:8202/mcp`;
  119. - data directory: `~/.okto_nexus`;
  120. - database: `~/.okto_nexus/nexus.db`;
  121. - initial workspace context: the current directory. The dashboard keeps a
  122. saved selection when present and otherwise may open the all-workspaces view.
  123. Useful variants:
  124. ```bash
  125. okto-nexus serve --project-root /absolute/path/to/project
  126. okto-nexus serve --host 127.0.0.1 --port 8202 # loopback-only access
  127. okto-nexus serve --trust-mode strict
  128. okto-nexus serve --embedding-mode local
  129. ```
  130. From another computer, use `http://<server-network-IP>:8202/`. Remote dashboard
  131. access requires an operator login configured locally in **Settings → Operator access**.
  132. MCP and Connector clients continue to authenticate with agent API keys.
  133. `--host` overrides `OKTO_NEXUS_HOST`; either can restrict the listening address.
  134. On first use, open **Agents → New agent** in the dashboard. Create one identity
  135. per participant and copy its `nxs_...` key immediately: Nexus stores only the
  136. hash and shows plaintext only at creation or regeneration. Capability and tag
  137. values must first exist in **Registry** before an identity can use them.
  138. ### Run harness teams
  139. A worker that runs under a harness needs four things before the hub starts
  140. its work from a broadcast handoff. Each item below is a separate gate.
  141. 1. Discovery roots. Pass them to `serve`:
  142. - `--harness-root P` approves one installation root. Repeat the flag for
  143. each trusted directory. The hub accepts at most 32 roots.
  144. - `--pi-install-root P` and `--pi-node P` set the Pi installation. Use
  145. both flags together. Use `--pi-node` only for a Node executable.
  146. - Each path must be absolute and must exist. The hub resolves symbolic
  147. links and uses the resolved path. A path that does not resolve is
  148. refused at startup. The flags do not add directories to PATH.
  149. 2. Execution grant. The agent needs a current grant with the `execute_work`
  150. action. Finding an installation does not give authority.
  151. 3. Agent opt-in. Set `broadcast_handoff_auto_claim` for the agent, or for the
  152. global default, in the runtime policy. The default is off for each agent.
  153. 4. Startup gate. The hub starts auto-claim only when both
  154. `runtime_handoff_auto_claim_enabled` (default true; env
  155. `OKTO_NEXUS_RUNTIME_HANDOFF_AUTO_CLAIM_ENABLED`) and
  156. `feature_harness_integrations` (default true) are on. If one is off,
  157. the hub does not start new work. Recovery of existing work continues.
  158. Details: [R4 operations guide](docs/harness-integrations/r4-operations.md).
  159. ## Connect an MCP client
  160. Configure the selected MCP client to use this streamable-HTTP endpoint:
  161. ```text
  162. http://127.0.0.1:8202/mcp
  163. ```
  164. Send the existing agent key in the `Authorization: Bearer nxs_...` header.
  165. The HTTP endpoint still accepts older query-key configurations during
  166. migration, but new configurations should keep the key out of the URL.
  167. Generic client configuration shape (use the fields your client supports):
  168. ```json
  169. {
  170. "mcpServers": {
  171. "okto-nexus": {
  172. "url": "http://127.0.0.1:8202/mcp",
  173. "headers": {"Authorization": "Bearer nxs_REPLACE_ME"}
  174. }
  175. }
  176. }
  177. ```
  178. ## Agent pre-flight
  179. Every authenticated agent should do this on its first turn:
  180. 1. Call `agent_whoami()`, use the returned `agent_id` consistently, and treat
  181. its `role` and `communication.content` as the default operating contract.
  182. 2. Call `workspace_resolve(project_root=<absolute cwd>)`.
  183. 3. Call `session_open(agent_id=<you>, workspace_id=<resolved id>)` and retain
  184. the returned `session_id` and one-time `session_secret`.
  185. 4. Check `inbox_count(agent_id=<you>)`; pull and acknowledge backlog.
  186. 5. Anchor monitoring with
  187. `event_cursor(project_root=..., agent_id=<you>, stream="workspace")`.
  188. The full procedure is available at
  189. `okto-nexus://reference/preflight`.
  190. The role guides responsibilities, operating perspective, and decision
  191. boundaries. The communication block guides tone, format, language, verbosity,
  192. structure, and agent-to-agent as well as user-facing communication. Follow both
  193. unless the user explicitly directs otherwise for the current task or
  194. interaction. That task-scoped override does not modify the Nexus profile or
  195. bypass permissions, policies, guardrails, approvals, communication scope,
  196. safety rules, or higher-priority host instructions. Capabilities are routing
  197. claims, not authorization or persona.
  198. ### Direct message
  199. ```json
  200. {
  201. "project_root": "/absolute/path/to/project",
  202. "from_agent_id": "researcher",
  203. "subject": "API findings",
  204. "body": "The endpoint is idempotent; details are attached.",
  205. "target": {
  206. "strategy": "direct",
  207. "agent_id": "implementer"
  208. },
  209. "from_session_id": "ses_...",
  210. "session_secret": "..."
  211. }
  212. ```
  213. The response names the resolved recipients and delivery count. The recipient
  214. uses:
  215. ```text
  216. inbox_count(agent_id="implementer")
  217. inbox_pull(agent_id="implementer", session_id="ses_...", session_secret="...")
  218. inbox_ack(agent_id="implementer", message_ids=[...],
  219. session_id="ses_...", session_secret="...")
  220. ```
  221. Messages are delivered through the inbox. `event_get` and `event_wait` are
  222. observability tools, not delivery.
  223. ### Long-poll
  224. `event_wait` is a snapshot when `timeout_seconds` is omitted, null, or `0`.
  225. Long-poll is explicit:
  226. ```text
  227. event_wait(
  228. project_root="/absolute/path/to/project",
  229. agent_id="researcher",
  230. stream="workspace",
  231. cursor=123,
  232. timeout_seconds=25,
  233. profile="summary"
  234. )
  235. ```
  236. Always continue from `next_cursor`. The waiter uses SQLite
  237. `PRAGMA data_version` plus bounded sleep polling; HTTP runs the blocking wait
  238. in a worker thread so it does not block the shared event loop.
  239. ## Architecture
  240. ```text
  241. MCP HTTP REST / SSE / SPA CLI
  242. \ | /
  243. +----------- inbound adapters and transport auth ----------+
  244. |
  245. application services
  246. identity · messages · inbox · handoffs · events · artifacts
  247. permissions · policies · approvals · guardrails · memory · health
  248. |
  249. domain models and pure rules
  250. |
  251. +------------------------- outbound ports ---------------------------+
  252. | SQLite repositories | files/shared.md | waiter | telemetry | embed |
  253. +--------------------------------------------------------------------+
  254. ```
  255. `bootstrap()` resolves configuration, creates the store, applies migrations,
  256. wires repositories, telemetry, embeddings, and approval execution, then seeds
  257. the reserved `operator`, backfills the capability catalog, and creates built-in
  258. permission/communication presets. `create_server()` lazily imports FastMCP and
  259. registers the effective tools and resources. `serve` wraps the same composition
  260. in FastAPI/Uvicorn; `tail` and `admin` are separate CLI adapters.
  261. Important boundaries:
  262. - domain code contains state machines, routing, IDs, and invariants;
  263. - application services own the core coordination use cases; operator
  264. CRUD/maintenance routes may drive repositories and units of work directly;
  265. - inbound adapters translate MCP, HTTP, SSE, and CLI calls;
  266. - outbound adapters implement SQLite, files, telemetry, tokenization,
  267. embeddings, and waiting;
  268. - coordination truth is durable in SQLite; bounded process caches are
  269. implementation details, not authoritative state.
  270. ## HTTP surfaces and authentication
  271. | Surface | Direct loopback client | Remote client |
  272. |---|---|---|
  273. | SPA shell/assets, `/healthz`, info, license | Public | Public |
  274. | Dashboard REST data/control plane | Keyless operator trust | Human operator session |
  275. | MCP `/mcp` | Active `nxs_` key required | Active `nxs_` key required |
  276. | EPT monitor endpoints | Scoped `nxsept_` accepted | Scoped `nxsept_` accepted |
  277. MCP-over-HTTP connections always represent an agent. The dashboard/REST loopback trust path represents
  278. the local operator. Browser-origin checks protect mutating operator routes, and
  279. binding to `0.0.0.0` preserves direct loopback access. Forwarded requests never
  280. inherit loopback trust. Agent REST/MCP credentials remain separate from UI sessions.
  281. For remote UI access, open the dashboard locally at `http://127.0.0.1:8202`,
  282. then set a username and password under **Settings → Operator access**. Remote
  283. browsers use **Operator sign-in**, not an agent API key. Passwords require at
  284. least 12 characters and are salted and hashed. Sessions expire after eight
  285. hours and use HttpOnly, SameSite cookies (Secure over HTTPS). Sign out revokes
  286. the session; changing the password revokes all sessions. Local access can reset
  287. a forgotten password; remote changes require the current password.
  288. The separate `operator-auth.db` in the Nexus home stores credential hashes,
  289. session hashes, and bounded human-action audit records, without agent keys.
  290. Startup no longer issues an agent key for dashboard login. HTTPS protects
  291. credentials and session traffic when using the dashboard across a network.
  292. Permanent agent keys can authenticate REST and MCP, but helper monitors should
  293. receive only a short-lived ephemeral poll token (`nxsept_...`). EPTs are bound
  294. to the issuing session, agent, and workspace and are accepted only as
  295. `Authorization: Bearer nxsept_...`; query `api_key` and `x-api-key` are rejected
  296. for this token type. The bearer is valid only on:
  297. - `GET /api/v1/events` and `GET /api/v1/events/cursor`;
  298. - `GET /api/v1/inbox/count` and `GET /api/v1/inbox/peek`.
  299. They cannot call MCP or mutate state.
  300. ## Dashboard
  301. The bundled dashboard provides:
  302. - **Graph** — toggle between detailed agent cards and compact activity-sized
  303. circles, with profile colours, live presence status badges, recent
  304. message flow, unread traffic, open handoffs, and claimed relationships;
  305. - **Messages** — inbox lanes, peer conversations, undelivered targeting
  306. outcomes, receipts, and optional semantic search;
  307. - **Handoffs** — a six-column Kanban including `VERIFYING`, claim details,
  308. dependency state, verification, cancellation, and results;
  309. - **Meta-harness** — an OpenAI-style chat for private or broadcast messages
  310. and handoffs, with agent filtering, aggregated acknowledgement flags, and
  311. replies/results in one timeline;
  312. - **Artifacts** — paginated deliverables with list/Explorer-style grid views,
  313. type-aware icons, rich previews, metadata, and managed-payload downloads;
  314. - **Events** — filtered event history, trace navigation, and live SSE updates;
  315. - **Memory** — durable memory browse/search/curation when `feature_memory` is
  316. enabled;
  317. - **Workspaces** — sessions, analytics, and coordination health;
  318. - **Agents** — identities, keys, activation, roles, capabilities, metadata,
  319. colors, permissions, tags, inbound/outbound audiences, communication style,
  320. and steering;
  321. - **Registry** — operator-managed capability and tag vocabularies;
  322. - **Policies** — versioned policies and per-agent bindings;
  323. - **Guardrails** — groups, versioned content rules, assignments, and scrubbed
  324. denial audit;
  325. - **Communication** — versioned communication presets and bindings;
  326. - **Approvals** — pending, decided, and archived human-in-the-loop actions.
  327. Use **Archive** to dismiss a stale or expired request and remove it from the
  328. pending badge. The **Archived** tab retains the original request, decision,
  329. result, archive time, and operator. Archiving does not grant permission,
  330. send a native answer, cancel an already submitted action, or resume a waiting
  331. harness. New decisions on archived requests are blocked. The operator-only
  332. `POST /api/v1/approvals/{approval_id}/archive` endpoint is idempotent;
  333. - **Settings** — runtime-manageable settings, feature flags, retention, and
  334. database maintenance; metrics use their own header-menu panel.
  335. Semantic search requires `embedding_mode=stub` or `local`. `off` returns
  336. `EMBEDDINGS_UNAVAILABLE` on the REST search endpoint. The `local` provider
  337. needs the embeddings extra; `stub` is deterministic and is intended for tests
  338. or demonstrations.
  339. ## Coordination model
  340. ### Workspaces, agents, and sessions
  341. - Agents are global identities; workspaces represent canonical project roots.
  342. - Most coordination tools accept `project_root`.
  343. - `session_open` and `shared_md_render` consume a resolved `workspace_id`.
  344. - An authenticated agent can update only its own profile with
  345. `agent_register`, subject to `identity.update_profile` and
  346. `identity.update_capabilities`. Operators create identities.
  347. - Authenticated discovery is reachability-scoped. `agent_list` and
  348. `agent_get` hide unreachable peers; `capability_list` returns the complete
  349. catalog but filters owner identities.
  350. - `workspace_list` is permission-gated; absolute paths require a separate
  351. permission.
  352. - Cross-workspace errors are intentionally operation-specific:
  353. `WORKSPACE_MISMATCH` for ownership guards, `NOT_FOUND` for hidden artifact or
  354. memory reads, and `DEPENDENCY_NOT_FOUND` for dependency creation.
  355. Presence is explicit. A session is considered present while its heartbeat is
  356. within `presence_ttl_seconds`. A trust-sensitive write advances the heartbeat
  357. only when it authenticates with that session's credentials; in
  358. `trust_mode=open`, a credential-free write advances no session. Read-only tools
  359. do not heartbeat. Call `session_heartbeat` during long read-only or idle periods
  360. and `session_close` when finished.
  361. ### Messages and inboxes
  362. `message_create` persists one message and resolves recipients at send time.
  363. Each recipient gets a durable delivery row in its global inbox. The lanes are:
  364. | Lane | Meaning |
  365. |---|---|
  366. | `unread` | Available to pull |
  367. | `delivered` | Pulled and protected by an in-flight lease |
  368. | `read` | Acknowledged |
  369. | `parked` | Dead-lettered after exhausting delivery claims; not redelivered automatically |
  370. An expired `delivered` lease becomes pullable again. Delivery is therefore
  371. at-least-once until acknowledgement. `message_status` lets the sender inspect
  372. each recipient's lane. Every pull/redelivery emits `message.delivered`; ack
  373. emits `message.read`. By default, ack also sends one synthetic read-receipt
  374. message to the sender; receipts do not recursively create receipts.
  375. Channels are organizational labels, not ACLs or delivery mechanisms. Access
  376. still intersects with permissions, policy, guardrails, and communication
  377. reachability. Message retention can remove aged messages and their deliveries,
  378. including unread or in-flight rows, so durability is bounded by configured
  379. retention and explicit database reset.
  380. ### Communication intent
  381. Choose the coordination mechanism by intended outcome: if another agent is
  382. expected to perform work or produce a deliverable, create a handoff. If the
  383. recipient only needs to know something or reply, use a message.
  384. - **Handoff — executable work.** Any request to execute, investigate, change,
  385. build, test, review, validate, or otherwise produce a deliverable must use
  386. `handoff_create`; a direct message must not be its sole record. Target the
  387. intended assignee directly when known, or use a capability, role, tag, mixed,
  388. broadcast, or direct-with-fallback target when the first eligible claimant
  389. should own the work. The handoff is the canonical, operator-visible record of
  390. ownership, lifecycle, result, and verification. Include the objective,
  391. context, scope, constraints, and expected deliverable; add acceptance
  392. criteria, dependencies, and a verifier when applicable and the corresponding
  393. `feature_verification` / `feature_dag` flag is enabled. Those fields are
  394. rejected while their feature is off.
  395. - **Broadcast message — shared alignment.** Use it for shared context,
  396. decisions, announcements, discoveries, risk or blocker alerts, and general
  397. alignment across every selected reachable recipient. It informs recipients
  398. but assigns no owner and creates no task lifecycle. If anyone is expected to
  399. act, create one or more handoffs.
  400. - **Direct message — conversation and informal coordination.** Use it for
  401. status checks, questions, clarifications, acknowledgements, focused context
  402. exchange, and informal coordination. It may discuss an existing handoff, but
  403. new executable work requires a handoff; reference that handoff in the
  404. conversation. Use `handoff_get` for canonical lifecycle state and direct
  405. messages for contextual updates or blocker explanations.
  406. A broadcast message is informational fan-out to many recipients. A handoff
  407. with a `broadcast` target is a claim pool for one executor. If several agents
  408. must produce independent results, create separate handoffs.
  409. ### Routing
  410. There are seven strategies:
  411. | Strategy | Descriptor | Notes |
  412. |---|---|---|
  413. | `direct` | `{"strategy":"direct","agent_id":"a"}` | One named identity |
  414. | `capability` | `{"strategy":"capability","capability":"review"}` | One or any of several registered capabilities |
  415. | `role` | `{"strategy":"role","role":"reviewer"}` | Exact role match |
  416. | `tag` | `{"strategy":"tag","selector":{"team":["platform"]}}` | Registered tag selector |
  417. | `broadcast` | `{"strategy":"broadcast"}` | Present workspace agents for messages; globally registered eligible agents for handoffs |
  418. | `mixed` | `{"strategy":"mixed","rules":[...]}` | Non-empty union of non-broadcast rules |
  419. | `direct_with_fallback` | direct plus `fallback_after_seconds` and optional `fallback` | Handoffs only |
  420. Messages support direct, capability, role, tag, broadcast, and mixed.
  421. Omitting a message target means broadcast. Handoffs require an explicit target
  422. and additionally support direct-with-fallback.
  423. Tag selectors use AND across keys and OR across values. Rich
  424. `In`/`NotIn`/`Exists`/`DoesNotExist` expressions are also supported.
  425. Capability and tag names fail closed against operator-managed catalogs.
  426. Target resolution is intersected with presence where applicable and with the
  427. caller's effective communication reach/audience. Separate enforcement layers
  428. then allow, deny, limit, or intercept the write:
  429. - per-agent permissions and recipient/rate limits;
  430. - versioned policy action rules and quotas;
  431. - content guardrails;
  432. - optional HITL approval interception.
  433. A channel itself adds no ACL. Visibility controls who may see an item;
  434. eligibility controls who may claim it.
  435. ### Event log
  436. Events are immutable after insertion during normal operation. `event_id` is
  437. globally monotonic and never reused. Retention may delete old rows, so retained
  438. history can contain gaps.
  439. Streams are `workspace`, `agent`, and `handoff`. Supported filters are
  440. `type`, `agent_id`, `task_id`, `handoff_id`, and `trace_id`. Authenticated event
  441. reads require `events.read` and omit actors outside the caller's communication
  442. reach, except the caller's own and system events.
  443. Response profiles:
  444. | Profile | Behavior |
  445. |---|---|
  446. | `default` | Safe trim: preserves contextual fields while removing empty or duplicated data; oversized event payloads can yield a follow-up hint |
  447. | `summary` | Aggressive projection: omits heavy bodies/payloads and returns follow-up hints |
  448. | `full` | Raw debugging escape hatch |
  449. `event_get` is non-blocking. `event_cursor` returns the current end in O(1).
  450. `event_wait` long-polls only when `timeout_seconds > 0`. Dashboard SSE already
  451. provides operator UI updates; agent monitoring remains MCP polling/long-poll or
  452. the EPT read-only REST plane.
  453. ### Handoffs
  454. ```text
  455. OPEN -> CLAIMED
  456. OPEN -> REJECTED | CANCELLED
  457. CLAIMED -> COMPLETED
  458. CLAIMED -> VERIFYING when acceptance criteria exist
  459. CLAIMED -> REJECTED claimant rejects
  460. CLAIMED -> OPEN lease expires
  461. VERIFYING -> COMPLETED verifier passes
  462. VERIFYING -> CLAIMED verifier fails; executor reworks
  463. ```
  464. Only one agent wins `handoff_claim`. A claim returns the confidential payload.
  465. Available-list responses omit payload; `handoff_get` includes it only for the
  466. claimant. Events and synthetic notifications never carry the payload.
  467. With `feature_verification=true`, creation may include
  468. `acceptance_criteria` and `verify_by`. The executor cannot verify its own
  469. result. A failed verdict persists feedback, returns the handoff to `CLAIMED`,
  470. and renews the lease.
  471. With `feature_dag=true`, creation may include `depends_on`. The persisted
  472. status remains `OPEN`, but blockedness is derived. Blocked items are excluded
  473. from `handoff_list_available` and claim returns `DEPENDENCY_NOT_MET` until every
  474. dependency is `COMPLETED`.
  475. ### Artifacts and `shared.md`
  476. Artifacts are published as `text`/`json`/`markdown`/`html` content or imported from a
  477. workspace-contained file. Path containment is checked after canonical
  478. resolution; escapes return `PATH_OUTSIDE_WORKSPACE`. Text content is bounded by
  479. `max_inline_bytes`.
  480. Payload bytes and free-form metadata do not live in SQLite. The database keeps
  481. only the minimal searchable and authorization catalog. The default local
  482. `ArtifactStore` adapter writes each payload and its `manifest.json` below
  483. `~/.okto_nexus/artifacts/<workspace>/<agent>/<artifact-id>/`. Imported files
  484. are copied into that managed location, so the artifact survives later changes
  485. to the original workspace file. The dashboard's **Artifacts** screen pages
  486. through the managed payload catalog, filters by one or more producing agents
  487. and a production date interval, and previews or downloads the selected payload.
  488. The publisher's effective outbound audience is frozen on the artifact. The
  489. same audience controls `artifact.created` visibility and `artifact_get`.
  490. Unauthorized, cross-workspace, and missing reads all return `NOT_FOUND`.
  491. `shared_md_render` atomically rewrites a derived workspace `shared.md` with four
  492. fixed sections: relevant agents/sessions, open tasks, open handoffs, and recent
  493. events. It never becomes the source of truth and never renders handoff payloads.
  494. Authenticated callers need `shared_md.render`.
  495. ### Permissions, policies, guardrails, and approvals
  496. The operator control plane manages:
  497. - permission presets and per-agent effective permissions;
  498. - capability/tag catalogs and communication scopes;
  499. - versioned attachable policies with deny-overrides and quota windows;
  500. - versioned communication guidance returned privately by `agent_whoami`;
  501. - agent groups and versioned guardrails assigned by scope and priority;
  502. - one-shot HITL approval decisions and operator steering.
  503. Guardrail denials persist scrubbed metadata, not rejected raw content. When
  504. `feature_hitl=true` and a policy requires approval, `message_create` or
  505. `handoff_create` may return `status: "pending_approval"`. Do not resend the
  506. action; watch the returned approval ID.
  507. ### Opt-in features
  508. All seven flags default to off:
  509. | Flag | Effect |
  510. |---|---|
  511. | `feature_trace` | Accept and project `trace_id` correlation |
  512. | `feature_hitl` | Enable new `require_approval` interception |
  513. | `feature_verification` | Enable handoff acceptance criteria and verdicts |
  514. | `feature_dag` | Enable handoff dependencies |
  515. | `feature_memory` | Register three memory MCP tools and show Memory UI; restart required |
  516. | `feature_health` | Enable `coordination_health` MCP execution |
  517. | `feature_replay` | Enable REST replay export |
  518. Nuances:
  519. - approval history and decisions remain available when interception is off;
  520. - disabling verification or DAG blocks new contracts/dependencies, while
  521. already persisted workflow state remains enforceable and decidable;
  522. - workspace health REST remains available when the MCP health flag is off;
  523. - CLI replay export is operator-shell access and is not gated by
  524. `feature_replay`;
  525. - memory REST supports operator curation independently, but MCP memory tools
  526. are registered only when the flag is on at startup.
  527. ### Chain limits
  528. Each root message has limits for the chain that it starts. A new root copies
  529. the values when the hub creates it. A change in **Settings** applies to new
  530. roots only. A cap error returns `QUOTA_EXCEEDED` to the caller.
  531. | Setting | Default | Range | Env var | Flag |
  532. |---|---|---|---|---|
  533. | `max_relay_depth` | 4 | 0 to 64 | `OKTO_NEXUS_MAX_RELAY_DEPTH` | `--max-relay-depth` |
  534. | `max_executions_per_root` | 16 | 1 to 1024 | `OKTO_NEXUS_MAX_EXECUTIONS_PER_ROOT` | `--max-executions-per-root` |
  535. | `root_deadline_seconds` | 1800 | 1 to 86400 | `OKTO_NEXUS_ROOT_DEADLINE_SECONDS` | `--root-deadline-seconds` |
  536. - `max_relay_depth` stops agents that relay work to each other without end.
  537. - `max_executions_per_root` limits the work that one root can start.
  538. - `root_deadline_seconds` closes a chain that runs too long.
  539. ## MCP surface
  540. HTTP MCP publishes the tools enabled by the startup configuration. Use
  541. `tools/list` and `nexus_info` for the effective surface and resource revisions.
  542. Memory adds three tools; enabled harness integration adds the eight runtime
  543. tools listed below. Nexus MCP stdio is no longer supported.
  544. | Area | Tools |
  545. |---|---|
  546. | Metadata | `nexus_info` |
  547. | Identity/workspace | `workspace_resolve`, `agent_register`, `agent_whoami`, `session_open`, `session_heartbeat`, `session_close`, `workspace_list`, `agent_list`, `agent_get`, `capability_list` |
  548. | Events | `event_get`, `event_cursor`, `event_wait` |
  549. | Messages/channels | `message_create`, `channel_create`, `channel_list`, `message_get`, `message_list`, `message_wait` |
  550. | Inbox | `inbox_pull`, `inbox_ack`, `inbox_extend`, `inbox_peek`, `inbox_count`, `inbox_history`, `message_status` |
  551. | Handoffs | `handoff_create`, `handoff_list_available`, `handoff_claim`, `handoff_complete`, `handoff_verify`, `handoff_reject`, `handoff_cancel`, `handoff_get` |
  552. | Artifacts | `artifact_put`, `artifact_get` |
  553. | Derived view | `shared_md_render` |
  554. | Health | `coordination_health` |
  555. | Catalog | `tag_list` |
  556. | Ephemeral monitor tokens | `poll_token_issue`, `poll_token_renew`, `poll_token_revoke` |
  557. | Optional memory | `memory_put`, `memory_get`, `memory_search` |
  558. | Optional runtime | `harness_list`, `harness_open`, `harness_send`, `harness_steer`, `harness_interrupt`, `harness_close`, `harness_get`, `harness_event_list` |
  559. `message_get`, `message_list`, and `message_wait` are intentional migration
  560. shims. They return `MIGRATED` with replacements in the inbox/event surface
  561. instead of failing as unknown tools.
  562. `coordination_health` stays registered but returns `VALIDATION_ERROR` while
  563. `feature_health` is off. `memory_put/get/search` are absent until
  564. `feature_memory` is enabled and the server restarts.
  565. Session credentials are trust-sensitive on:
  566. - `message_create`;
  567. - `handoff_claim/complete/verify/reject/cancel`;
  568. - `inbox_pull/ack/extend`;
  569. - `memory_put` when published.
  570. In `trust_mode=open` they are optional but validated if supplied. In
  571. `trust_mode=strict` they are required. `poll_token_issue/renew/revoke` always
  572. require a valid `session_id` and `session_secret` in both modes.
  573. ### Versioned MCP resources
  574. | URI | Version |
  575. |---|---:|
  576. | `okto-nexus://reference/preflight` | 4 |
  577. | `okto-nexus://reference/communication` | 3 |
  578. | `okto-nexus://reference/monitoring` | 5 |
  579. | `okto-nexus://reference/target-grammar` | 5 |
  580. | `okto-nexus://reference/tool-docs/messages` | 3 |
  581. | `okto-nexus://reference/tool-docs/inbox` | 2 |
  582. | `okto-nexus://reference/tool-docs/events` | 2 |
  583. | `okto-nexus://reference/tool-docs/handoff` | 4 |
  584. | `okto-nexus://reference/tool-docs/identity` | 5 |
  585. | `okto-nexus://reference/tool-docs/artifacts` | 4 |
  586. | `okto-nexus://reference/governance` | 2 |
  587. | `okto-nexus://reference/hitl` | 2 |
  588. `nexus_info` reports package/schema/surface versions, the URI-to-version map,
  589. and effective feature flags. Use that live metadata instead of assuming a
  590. cached surface.
  591. ### Response envelope
  592. Successful tools return:
  593. ```json
  594. {
  595. "ok": true,
  596. "data": {}
  597. }
  598. ```
  599. Failures return:
  600. ```json
  601. {
  602. "ok": false,
  603. "error": {
  604. "code": "VALIDATION_ERROR",
  605. "message": "Human-readable explanation"
  606. }
  607. }
  608. ```
  609. Transient SQLite lock/busy failures use `DB_ERROR` with
  610. `details.retryable=true`.
  611. ### Resident token footprint
  612. For the 0.1.10 default surface:
  613. | Component | Characters |
  614. |---|---:|
  615. | Server instructions | 3,992 |
  616. | Tool docstrings | 6,563 |
  617. | Parameter schemas/descriptions | 15,720 |
  618. | Cuttable resident surface | 26,275 (~6,568 tokens) |
  619. | Total measured surface | 37,345 (~9,336 tokens) |
  620. Deep explanations live in resources so clients load them only when needed.
  621. That historical measurement reported a cuttable reduction of about 44.3%
  622. against its frozen baseline; it is not a measurement of the R4 surface.
  623. ## Configuration
  624. ### One-shot runtime sessions and MCP presets (0.3.0)
  625. Select `one_shot` in the runtime session policy to create one single-use session
  626. per call. Global capacity defaults and independent agent overrides configure
  627. parallel executions, unused warm instances, queue size, overflow rejection,
  628. queue timeout and execution timeout. Set the parallel limit to **0** for no
  629. pool-specific ceiling; the host resource budget still applies. Warm instances
  630. must be fewer than a finite parallel limit: for example, 10 parallel and 5 warm. Starting and closing
  631. instances still occupy capacity; a successful response remains successful if
  632. resource cleanup needs another attempt. Queued calls run before replenishment.
  633. Each instance is claimed independently. Pool openings have a separate bounded
  634. dispatch budget, so slow replenishment cannot hold up ready sessions. Capacity
  635. is released only after confirmed disposal, never merely because a call ended
  636. or timed out. The connection wizard saves these settings on **Next**.
  637. Warm-up reserves the full deficit in one maintenance pass and starts independent
  638. opens in parallel, within host and transport credits. Calls arriving during
  639. warm-up reserve capacity without binding to a cold process: the oldest compatible
  640. caller receives the next ready instance. A slower opening cannot pin that caller
  641. while another compatible instance sits idle. No productive turn is sent until
  642. the resource is ready; cancellation and waiting deadlines remain durable.
  643. The pool and queue use hexagonal boundaries: `domain/resource_pool.py` contains
  644. the rules, `application/resource_pool.py` coordinates them through the ports in
  645. `application/resource_pool_ports.py`, and `adapters/outbound/sqlite/resource_pool.py`
  646. provides the internal durable implementation. `bootstrap/resource_pool.py`
  647. wires these adapters. Local and remote runtimes use the same allocation service;
  648. process operations continue through the authorized execution outbox.
  649. A future distributed adapter must atomically couple dequeue, capacity claims
  650. and outcomes with the execution outbox, preserving idempotency and fenced
  651. disposal. Replacing storage does not change the pool rules; a broker alone is
  652. not a substitute for this transactional contract.
  653. The agent settings show occupied capacity, queued calls, recent outcomes and
  654. cancellation controls. Capacity refusals return directly to the caller;
  655. broadcast responses identify refused recipients separately. Later failures
  656. create a correlated private inbox message for the original caller, including
  657. execution stage, possible effects and retry safety. These notices are durable
  658. coordination messages; they do not automatically start a new agent turn.
  659. Runtime harness settings also accept an MCP preset with `stdio` or `http`
  660. servers. Presets compose with the existing **inherit global MCPs** setting:
  661. an entry replaces the same inherited name, a disabled entry removes it, and
  662. Nexus integrations remain reserved. Use approved execution-host `env_refs`
  663. or `header_refs` for credentials, rather than literal secrets. Paths resolve
  664. on that host, including when using a remote Connector. Codex and Claude use
  665. their native MCP integration; Pi receives tools through a session-owned MCP
  666. bridge. A preset change applies to new sessions and retires incompatible unused
  667. warm instances. Resetting history with agent preservation keeps these settings.
  668. Implementation evidence is tracked in `plans/one_shot_mcp/ledger.json`.
  669. For `serve` settings managed by the runtime catalog, effective precedence is:
  670. ```text
  671. CLI flag > environment variable > stored dashboard override > default
  672. ```
  673. Within the shared bootstrap there is no stored layer, so precedence is
  674. `CLI > env > default`. Unknown flags, missing values, invalid enums, and
  675. out-of-range numbers fail closed with `CONFIG_ERROR`. Boolean CLI flags take
  676. an explicit value such as `--feature-trace true`.
  677. ### Core runtime
  678. | Environment | CLI | Default | Notes |
  679. |---|---|---:|---|
  680. | `OKTO_NEXUS_HOME` | `--home` | `~/.okto_nexus` | Runtime data directory |
  681. | `OKTO_NEXUS_DB_PATH` | `--db-path` | `{home}/nexus.db` | SQLite database |
  682. | `OKTO_NEXUS_BUSY_TIMEOUT_MS` | `--busy-timeout-ms` | 5000 | Minimum 0 |
  683. | `OKTO_NEXUS_POLL_INTERVAL_MS` | `--poll-interval-ms` | 200 | Waiter interval; minimum 1 |
  684. | `OKTO_NEXUS_RUNTIME_IDLE_INTERVAL_MS` | `--runtime-idle-interval-ms` | 1000 | Longest sleep of the serve runtime loops when no work is pending; 100 to 60000 |
  685. | `OKTO_NEXUS_MAX_WAIT_TIMEOUT_SECONDS` | `--max-wait-timeout-seconds` | 30 | Server wait ceiling; minimum 0 |
  686. | `OKTO_NEXUS_HANDOFF_LEASE_TTL_SECONDS` | `--handoff-lease-ttl-seconds` | 300 | Minimum 1 |
  687. | `OKTO_NEXUS_MAX_INLINE_BYTES` | `--max-inline-bytes` | 65536 | Inline artifact/content limit |
  688. | `OKTO_NEXUS_INBOX_LEASE_TTL_SECONDS` | `--inbox-lease-ttl-seconds` | 300 | Minimum 1 |
  689. | `OKTO_NEXUS_SESSION_STALE_TTL_SECONDS` | `--session-stale-ttl-seconds` | 60 | Derived stale threshold |
  690. | `OKTO_NEXUS_PRESENCE_TTL_SECONDS` | `--presence-ttl-seconds` | 1800 | Broadcast/tag presence window |
  691. | `OKTO_NEXUS_SESSION_REAP_SECONDS` | `--session-reap-seconds` | 86400 | Opportunistic stale close |
  692. | `OKTO_NEXUS_MAX_SHARED_MD_EVENTS` | `--max-shared-md-events` | 1000 | Render ceiling |
  693. | `OKTO_NEXUS_MAX_EVENT_LIMIT` | `--max-event-limit` | 1000 | Event page ceiling |
  694. | `OKTO_NEXUS_POLL_TOKEN_TTL_SECONDS` | `--poll-token-ttl-seconds` | 3600 | Minimum 60 |
  695. | `OKTO_NEXUS_TRUST_MODE` | `--trust-mode` | `open` | `open` or `strict` |
  696. | `OKTO_NEXUS_EMBEDDING_MODE` | `--embedding-mode` | `off` | `off`, `stub`, or `local` |
  697. | `OKTO_NEXUS_INBOX_READ_RECEIPTS` | `--inbox-read-receipts` | `true` | Sender inbox receipts |
  698. | `OKTO_NEXUS_META_HARNESS_RECEIPT_DISPLAY` | `--meta-harness-receipt-display` | `inline` | `inline` flags or legacy `timeline` messages |
  699. | `OKTO_NEXUS_EXPOSE_WORKSPACE_PATH` | `--expose-workspace-path` | `false` | Operator REST/dashboard path disclosure |
  700. | `OKTO_NEXUS_AUTO_PRUNE_ON_START` | `--auto-prune-on-start` | `false` | One bounded best-effort startup pass |
  701. ### Retention
  702. | Environment | CLI | Default | Minimum |
  703. |---|---|---:|---:|
  704. | `OKTO_NEXUS_RETENTION_EVENTS_KEEP_DAYS` | `--retention-events-keep-days` | 30 | 0 |
  705. | `OKTO_NEXUS_RETENTION_READ_DELIVERIES_KEEP_DAYS` | `--retention-read-deliveries-keep-days` | 14 | 0 |
  706. | `OKTO_NEXUS_RETENTION_CLOSED_SESSIONS_KEEP_DAYS` | `--retention-closed-sessions-keep-days` | 7 | 0 |
  707. | `OKTO_NEXUS_RETENTION_MESSAGES_KEEP_DAYS` | `--retention-messages-keep-days` | 30 | 7 |
  708. Pruning removes aged events, `read` deliveries, `closed` sessions, and messages
  709. older than the message window. Message retention is pure-age: it can remove
  710. unread, in-flight, or parked messages and cascades to their deliveries and
  711. embeddings. Handoffs and other non-message live rows are not age-pruned.
  712. ### Metrics
  713. | Environment | CLI | Default | Notes |
  714. |---|---|---:|---|
  715. | `OKTO_NEXUS_METRICS_MODE` | `--metrics-mode` | `disabled` | `disabled`, `local_only`, `anonymous_beacon` |
  716. | `OKTO_NEXUS_METRICS_DIR` | `--metrics-dir` | `{home}/metrics` | Local telemetry JSONL/state |
  717. | `OKTO_NEXUS_METRICS_BEACON_URL` | `--metrics-beacon-url` | `https://nexus-metrics.oktolabs.ai` | Used only in beacon mode |
  718. | `OKTO_NEXUS_TRANSPORT_SECURITY` | `--transport-security` | `http_https` | `http_https`: HTTP/HTTPS and WS/WSS; `https_only`: HTTPS/WSS only |
  719. **Settings → Transport security** controls the same global policy for the UI,
  720. HTTP APIs, MCP, and runtime WebSocket links. HTTP and WS are allowed over LAN
  721. by default; credentials and binding approvals are still required. `https_only`
  722. rejects plaintext requests, including loopback, with `TLS_REQUIRED` (HTTP 403).
  723. Configure TLS at the ASGI server before enabling this mode. This setting does
  724. not install certificates or enable TLS on the listener. It takes effect for new
  725. requests and connections; restart to close existing streams. Only the trusted
  726. ASGI scheme is used: raw client forwarding headers cannot bypass this policy.
  727. | `OKTO_NEXUS_METRICS_RETENTION_DAYS` | `--metrics-retention-days` | 30 | Minimum 0 |
  728. | `OKTO_NEXUS_METRICS_PUBLISH_INTERVAL_SECONDS` | `--metrics-publish-interval-seconds` | 3600 | Minimum 60 |
  729. Metrics are opt-in. Local mode stores bounded per-event metadata; beacon mode
  730. publishes aggregate hourly counts only. Message bodies, prompts, workspace file
  731. paths, coordination IDs, keys, tokens, URLs, and stack traces are excluded.
  732. Local telemetry JSONL is not currently pruned automatically; operators must
  733. manage those files even though `metrics_retention_days` is validated and
  734. exposed in configuration.
  735. ### Feature flags
  736. | Environment | CLI | Default |
  737. |---|---|---:|
  738. | `OKTO_NEXUS_FEATURE_TRACE` | `--feature-trace` | `false` |
  739. | `OKTO_NEXUS_FEATURE_HITL` | `--feature-hitl` | `false` |
  740. | `OKTO_NEXUS_FEATURE_VERIFICATION` | `--feature-verification` | `false` |
  741. | `OKTO_NEXUS_FEATURE_DAG` | `--feature-dag` | `false` |
  742. | `OKTO_NEXUS_FEATURE_MEMORY` | `--feature-memory` | `false` |
  743. | `OKTO_NEXUS_FEATURE_HEALTH` | `--feature-health` | `false` |
  744. | `OKTO_NEXUS_FEATURE_REPLAY` | `--feature-replay` | `false` |
  745. `feature_memory` changes tool registration and requires restart/reconnect.
  746. The other flags gate live behavior.
  747. ### Serve-only and transport-specific settings
  748. | Environment | CLI | Default | Scope |
  749. |---|---|---:|---|
  750. | `OKTO_NEXUS_PORT` | `--port` | 8202 | `serve` |
  751. | `OKTO_NEXUS_HOST` | `--host` | `0.0.0.0` | `serve` |
  752. | `OKTO_NEXUS_LOG_LEVEL` | `--log-level` | `warning` | `critical` through `trace` |
  753. | — | `--project-root` | `.` | Initial dashboard workspace |
  754. | `OKTO_NEXUS_NO_BANNER` | — | unset | Suppress serve banner |
  755. ## Operations
  756. ### CLI commands
  757. | Command | Purpose |
  758. |---|---|
  759. | `okto-nexus serve` | Start MCP HTTP, REST, SSE, and dashboard |
  760. | `okto-nexus` | Show CLI help |
  761. | `okto-nexus tail` | Operator NDJSON follower over the event service |
  762. | `okto-nexus admin prune` | Enforce retention, optionally vacuum |
  763. | `okto-nexus admin issue-keys` | Add keys to legacy keyless identities |
  764. | `okto-nexus admin export` | Export a workspace replay stream as NDJSON |
  765. | `okto-nexus admin migrate-mcp-entry` | Migrate one selected Nexus stdio config entry to HTTP |
  766. Use `--help` on every command for the full argument grammar.
  767. ### Tail
  768. ```bash
  769. okto-nexus tail \
  770. --project-root /absolute/path/to/project \
  771. --agent-id observer \
  772. --stream workspace \
  773. --from latest
  774. ```
  775. `tail` applies per-agent event visibility. An optional `--cursor-file` belongs
  776. to that consumer only; corrupted checkpoints fail closed.
  777. ### Retention
  778. Start with a dry run:
  779. ```bash
  780. okto-nexus admin prune \
  781. --project-root /absolute/path/to/project \
  782. --dry-run
  783. ```
  784. Then execute:
  785. ```bash
  786. okto-nexus admin prune \
  787. --project-root /absolute/path/to/project \
  788. --messages-keep-days 30 \
  789. --vacuum
  790. ```
  791. Retention spans the whole shared store even though `--project-root` is
  792. validated as the command anchor. `--vacuum` is the only option that compacts
  793. freed pages on disk. There is no always-running coordination reaper;
  794. `auto_prune_on_start` is a bounded opportunistic pass.
  795. ### Issue legacy keys
  796. ```bash
  797. okto-nexus admin issue-keys \
  798. --project-root /absolute/path/to/project
  799. ```
  800. This is additive and idempotent. Existing keys are never rotated. Newly issued
  801. plaintext keys are printed once.
  802. ### Replay export
  803. ```bash
  804. okto-nexus admin export \
  805. --project-root /absolute/path/to/project \
  806. --trace-id trc_... \
  807. --output nexus-events.ndjson
  808. ```
  809. The first line is a manifest; subsequent lines are raw events ordered by
  810. `event_id`. CLI export is operator-shell access and remains available even
  811. when the REST replay flag is off.
  812. ### Selected MCP config migration
  813. Set `OKTO_NEXUS_MCP_KEY` in the operator environment to the selected agent's
  814. existing `nxs_` key. The command never issues or rotates a key. Plan a change
  815. to one explicitly chosen entry:
  816. ```bash
  817. okto-nexus admin migrate-mcp-entry --config /path/to/.mcp.json \
  818. --entry okto-nexus --url http://127.0.0.1:8202/mcp
  819. ```
  820. Review the redacted diff summary and its full `expected_sha256`, then apply
  821. with `--apply --expected-sha256 <reviewed-hash>`. The command backs up the
  822. original file and refuses concurrent edits. Other `mcpServers` entries retain
  823. their values. It rejects entries with environment values or unknown fields
  824. that need a manual migration.
  825. ### Ephemeral monitor token
  826. An authenticated agent can call `poll_token_issue`, give only the returned
  827. `nxsept_...` token and base URL to a read-only helper, renew it before expiry,
  828. and revoke it on teardown. The raw token is returned only on issue/renew.
  829. ## Data model and migrations
  830. The core coordination tables include:
  831. | Area | Tables |
  832. |---|---|
  833. | Core coordination | `schema_migrations`, `workspaces`, `agents`, `sessions`, `events`, `channels`, `messages`, `tasks`, `handoffs`, `artifacts`, `message_deliveries` |
  834. | Settings/security/catalogs | `settings`, `permission_presets`, `tag_keys`, `tag_values`, `capability_names`, `ephemeral_poll_tokens` |
  835. | Search and memory | `message_embeddings`, `memories`, `memory_embeddings` |
  836. | Governance/workflows | `governance_policies`, `approvals`, `handoff_dependencies`, `policies`, `policy_versions`, `agent_policy_bindings`, `comm_presets`, `comm_preset_versions`, `agent_comm_binding`, `agent_groups`, `agent_group_members`, `guardrails`, `guardrail_versions`, `guardrail_assignments` |
  837. Not every table is workspace-scoped: agents and catalogs are global, inbox
  838. deliveries are keyed by recipient identity, and bindings/control-plane records
  839. have their own ownership rules.
  840. Migrations are embedded in the package and applied in order. The following list
  841. describes the early coordination migrations; it is not the complete R4 schema:
  842. - **001–008:** core schema, close metadata, handoff payload/result, presence,
  843. durable inbox deliveries, leases, and session secrets;
  844. - **009–015:** API keys, settings, permissions, embeddings, tags/scopes,
  845. capability catalog, and trace IDs;
  846. - **016–021:** governance, approvals, verification, dependencies, memory, and
  847. health/event indexes;
  848. - **022–026:** versioned attachable policies, communication presets, display
  849. colors, groups/guardrails, and ephemeral poll tokens.
  850. Automatic runtime recovery is enabled by default under **Settings → Global runtime defaults**.
  851. Recovery scheduling and delivery defaults come from Core's `RuntimeAutomation`
  852. API, also used by Connector CLI. Nexus retains its transactional inbox and
  853. authorization checks; the embedded host does not maintain a separate retry policy.
  854. Connector clients can test reachability without credentials using `GET /v1/reach`
  855. or `okto-nexus-connector reach --server <base-url>`. The public, read-only endpoint
  856. returns the installed `server_version`, installed `server_core_version` (or
  857. `null` if Core is absent), and `minimum_cli_version`. The minimum CLI version is
  858. maintained in `application/reach.py` with the supported management contract.
  859. On restart, Nexus reconciles retained local sessions against Core ownership,
  860. resource-release and event-history proofs before admitting new work. A dispatch
  861. refusal that provably never called Core does not require a nonexistent session
  862. journal. Previously submitted messages are never automatically replayed.
  863. New messages arriving during recovery stay unclaimed in a durable queue. The
  864. Meta-harness shows **Waiting for runtime recovery**; MCP can still consume them.
  865. Before admission, Nexus revalidates the original sender credentials and current
  866. execution authorization. Recovery uses five retries with bounded backoff. An
  867. unresolved message moves to **Runtime recovery needs attention** after bounded
  868. queue checks. Inspect **Execution log** for recovery diagnostics. Disabling the
  869. global option stops automatic retries and deferred delivery; it does not grant
  870. permission to reuse uncertain sessions. Changes to the Core installation or its
  871. inventory may still require reviewing the connection configuration.
  872. Nexus refuses to run against an unsupported newer schema. Runtime SQLite
  873. databases and their WAL/SHM/journal sidecars are ignored and must not be
  874. committed.
  875. ## Errors
  876. The domain/MCP contract has a closed catalog of 29 canonical codes:
  877. | Area | Codes |
  878. |---|---|
  879. | Workspace | `WORKSPACE_REQUIRED`, `WORKSPACE_UNRESOLVED`, `WORKSPACE_MISMATCH` |
  880. | Validation/identity | `VALIDATION_ERROR`, `NOT_FOUND`, `NOT_OWNER`, `PERMISSION_DENIED` |
  881. | Catalog/control plane | `TAG_IN_USE`, `CAPABILITY_IN_USE`, `POLICY_IN_USE`, `COMM_PRESET_IN_USE` |
  882. | Governance | `POLICY_DENIED`, `QUOTA_EXCEEDED`, `GUARDRAIL_DENIED`, `CONFLICT` |
  883. | Dependencies/state | `DEPENDENCY_NOT_FOUND`, `DEPENDENCY_NOT_MET`, `INVALID_TRANSITION`, `INVALID_STREAM` |
  884. | Handoffs | `HANDOFF_ALREADY_CLAIMED`, `NOT_ELIGIBLE_TO_CLAIM` |
  885. | Content/path | `CONTENT_TOO_LARGE`, `PATH_OUTSIDE_WORKSPACE` |
  886. | Infrastructure | `CONFIG_ERROR`, `MIGRATION_ERROR`, `DB_ERROR`, `RENDER_ERROR` |
  887. | Compatibility/internal | `MIGRATED`, `INTERNAL_ERROR` |
  888. REST adapters also use transport-specific codes such as `AUTH_FAILED`,
  889. `CROSS_ORIGIN_BLOCKED`, `INVALID_PARAM`, `INVALID_WINDOW`,
  890. `INVALID_SETTING`, `EMBEDDINGS_UNAVAILABLE`, and `INTERNAL`.
  891. ## Development
  892. ```bash
  893. uv sync --extra dev
  894. uv run pytest -q
  895. ```
  896. For the complete HTTP/embedding environment:
  897. ```bash
  898. uv sync --extra serve --extra dev
  899. uv run pytest -q
  900. ```
  901. Frontend:
  902. ```bash
  903. cd frontend
  904. npm ci
  905. npm run build
  906. ```
  907. The build writes packaged static assets under
  908. `src/okto_nexus/adapters/inbound/http/static/`.
  909. Release checks:
  910. ```bash
  911. uv lock --check
  912. uv build --out-dir dist/release-0.3.0
  913. uvx twine check \
  914. dist/release-0.3.0/okto_nexus-0.3.0-py3-none-any.whl \
  915. dist/release-0.3.0/okto_nexus-0.3.0.tar.gz
  916. ```
  917. Publish only explicitly named current-version artifacts. The top-level
  918. `dist/` may contain older builds.
  919. ### Project layout
  920. ```text
  921. src/okto_nexus/
  922. adapters/
  923. inbound/
  924. cli/ serve, tail, admin
  925. http/ FastAPI, REST, SSE, packaged SPA
  926. mcp/ HTTP server, resources, projections, configured tools
  927. outbound/
  928. sqlite/ repositories and migrations adapter
  929. embedding/ optional semantic provider
  930. file/ sharedmd/ artifact and derived-view I/O
  931. telemetry/ tokenizer/ metrics support
  932. application/ use cases and ports
  933. domain/ entities, routing, state machines, policies
  934. migrations/ 001 through 027
  935. testing/ reusable test/replay harnesses
  936. frontend/ React dashboard source
  937. tests/ unit, contract, integration, replay tests
  938. docs/design/ architecture and design records
  939. pyproject.toml package metadata and extras
  940. uv.lock reproducible dependency lock
  941. ```
  942. ## Contributing
  943. See [CONTRIBUTING.md](CONTRIBUTING.md) for the supported Python and frontend
  944. development environments, validation commands, and pull-request workflow.
  945. ## Troubleshooting
  946. ### `event_wait` returns immediately
  947. Pass `timeout_seconds > 0`. Omitted, null, and zero are snapshots by design.
  948. ### An agent misses broadcasts
  949. Check that it opened a session in the correct resolved workspace and continues
  950. to heartbeat. Read-only event/inbox checks do not advance presence.
  951. ### A direct peer is missing from discovery
  952. Authenticated discovery is filtered by communication reachability. Inspect the
  953. caller's outbound and the peer's inbound communication scopes/tags in the
  954. dashboard.
  955. ### Capability or tag targeting fails
  956. Create the capability/tag value in **Registry** first. Catalog validation is
  957. fail-closed.
  958. ### Memory tools are absent
  959. Set `feature_memory=true` and restart/reconnect. Unlike live behavior flags,
  960. this flag changes MCP tool registration.
  961. ### Semantic search is unavailable
  962. Use `embedding_mode=stub` or install the embeddings/serve extra and use
  963. `embedding_mode=local`. `off` intentionally disables search.
  964. ### `DB_ERROR` reports a lock
  965. If `details.retryable=true`, retry the same call after the competing writer
  966. commits. Avoid opening the runtime SQLite file with tools that hold long write
  967. transactions.
  968. ### The hub says another server already owns the home
  969. `serve` holds `{home}/nexus.serve.lock` and refuses a second server using that
  970. same home. Stop the other hub or choose a different `--home`; changing only
  971. `--db-path` does not change the lock scope.
  972. ### Workspace path is rejected
  973. Pass an existing absolute path. Nexus canonicalizes the real path before
  974. deriving the workspace ID and validating artifact containment.
  975. ### A monitor cannot mutate state
  976. That is expected for `nxsept_` tokens. They are intentionally read-only and
  977. accepted only on the four monitor endpoints.
  978. ### Cached docs appear stale
  979. Call `nexus_info` and compare `surface_revision` and `resource_versions` before
  980. reusing cached MCP reference content.
  981. ## Security and limitations
  982. Report vulnerabilities privately according to [SECURITY.md](SECURITY.md). Do
  983. not include vulnerability details, credentials, tokens, or private workspace
  984. data in a public issue.
  985. - Nexus is designed for local or controlled single-tenant coordination, not as
  986. a public multi-tenant broker.
  987. - It does not terminate TLS. Put an authenticated TLS reverse proxy in front
  988. of a remote bind.
  989. - The dashboard shell and public health/info/license assets remain public;
  990. data/control REST requires authentication outside loopback.
  991. - API keys are hash-only at rest and shown once. Regeneration invalidates the
  992. old key immediately.
  993. - Session secrets are stored in plaintext in the local SQLite database; anyone
  994. who can read that file is inside the session trust boundary.
  995. - Channels are labels, not security boundaries.
  996. - SQLite is the only built-in coordination store. There is no Redis,
  997. PostgreSQL, or cloud broker adapter.
  998. - There is no always-running coordination scheduler/reaper. Expiry is checked
  999. opportunistically and retention runs manually or at startup when enabled.
  1000. - The HTTP server does use worker threads/tasks for operational needs such as
  1001. blocking waits and telemetry; “no scheduler” does not mean “no threads.”
  1002. - Message durability is bounded by message retention and explicit reset.
  1003. - Memory is experimental and changes the MCP surface at startup.
  1004. - Artifact file references are confined to the canonical workspace.
  1005. - Avoid committing runtime databases, sidecars, metrics output, and local
  1006. secrets to version control.
  1007. ## Future direction
  1008. Likely extension points are additional durable-store adapters, a push-backed
  1009. waiter that removes internal sleep polling, stronger remote deployment
  1010. packaging, and further generated documentation from the live MCP schemas. The
  1011. delivered surface already includes permissions, catalogs, communication
  1012. scopes, policies, guardrails, HITL, trace correlation, verified/DAG handoffs,
  1013. memory, health, replay, ephemeral poll tokens, embeddings, metrics, REST, SSE,
  1014. and the dashboard.
  1015. ## Release notes
  1016. ### 0.1.10 — previous release
  1017. Validation-hardening release: lands the external PR backlog and closes the
  1018. open validation bugs (#26–#30). The MCP contract remains at surface revision
  1019. 33 and the latest database migration remains 028.
  1020. - Bumped the package and distribution metadata from 0.1.9 to 0.1.10.
  1021. - Capped message artifact references at 20 (`MAX_ARTIFACTS`) with `{count,
  1022. max}` diagnostics on both MCP and REST; the dashboard Meta-harness route
  1023. now defers to the domain cap (the legacy 10-attachment fence was removed)
  1024. and `VALIDATION_ERROR` details survive the REST envelope.
  1025. - Rejected exact-duplicate artifact references; the error names the
  1026. offending index and the duplicated reference.
  1027. - Capped tag selector value lists at 20 values per key with set-based
  1028. de-duplication, removing an O(n²) scan reachable from
  1029. `message_create`/`handoff_create` tag targets.
  1030. - Added length caps to the routing target grammar identifier fields
  1031. (`agent_id`/`role`/`capability`, 256 chars) and to each `depends_on` id
  1032. (128 chars).
  1033. - Resynced the dashboard ColorPicker draft when the `value` prop changes
  1034. while the component stays mounted.
  1035. - Consolidated the duplicated bounded-list count check into the shared
  1036. domain helper `check_list_size`.
  1037. ### 0.1.9
  1038. Dashboard presentation release. The MCP contract remains at surface revision
  1039. 33 and the latest database migration remains 028.
  1040. - Bumped the package and distribution metadata from 0.1.8 to 0.1.9.
  1041. - Added list/grid switching to the Artifacts catalog, including an
  1042. Explorer-style grid with type-aware file icons, names, and payload sizes.
  1043. - Collapsed Meta-harness read-receipt notifications into acknowledgement flags
  1044. on their original messages by default. Grey flags identify incomplete target
  1045. sets; green flags mean every target acknowledged, and their detail modal
  1046. identifies pending recipients and delivery/read timestamps.
  1047. - Added the `meta_harness_receipt_display` interface setting so operators can
  1048. restore separate receipt messages with the `timeline` mode.
  1049. ### 0.1.8
  1050. Artifact storage and catalog release. The MCP contract is at surface revision
  1051. 33 and the latest database migration is 028.
  1052. - Moved artifact payloads and free-form metadata out of SQLite into an
  1053. adapter-backed store, with a local filesystem adapter by default.
  1054. - Imported path-based artifacts into managed storage so they remain available
  1055. independently of the original workspace file.
  1056. - Added the Artifacts catalog with paginated producer/date filtering, detail
  1057. previews, expanded Raw/Rich rendering, and managed-payload downloads.
  1058. - Added rendered metadata fields plus safe Rich previews for Markdown, JSON,
  1059. and HTML artifacts.
  1060. ### 0.1.7
  1061. Dashboard usability and operator-interaction release. The MCP surface remains
  1062. unchanged; the latest database migration is 027.
  1063. - Added the Meta-harness chat with independent Message/Handoff and
  1064. Private/Broadcast controls.
  1065. - Combined outgoing turns, incoming agent messages, and handoff completion or
  1066. rejection outcomes in a live, agent-filterable timeline.
  1067. - Rendered structured chat content as readable labels and lists instead of raw
  1068. JSON.
  1069. - Reworked Guardrails group composition and rule authoring, including agent
  1070. auto-completion, capability-scoped assignments, regex assistance, and
  1071. stricter validation.
  1072. - Added completed-agent responses and rejection reasons to Handoff cards and
  1073. details.
  1074. - Removed nested page scrolling from the dashboard shell.
  1075. ### 0.1.6
  1076. Startup compatibility maintenance release. The MCP contract and database
  1077. schema are unchanged: surface revision remains 32 and the latest migration
  1078. remains 026.
  1079. - Rebuilt the MCP v1 FastMCP settings model after import, eliminating the
  1080. unresolved `lifespan` forward-reference warning introduced by
  1081. `pydantic-settings` 2.15.
  1082. - Applied the compatibility path to both stdio and streamable-HTTP server
  1083. construction.
  1084. - Constrained the MCP SDK dependency to `mcp>=1.0,<2` so adopting the breaking
  1085. v2 API requires an explicit migration.
  1086. - Added a regression test that promotes the startup warning to an error and
  1087. verifies the settings model is complete.
  1088. - Verified the installed executable with local MiniLM warm-up, a live health
  1089. request, and the complete test suite.
  1090. ### 0.1.5
  1091. Live MCP smoke-test maintenance release. The MCP contract and database schema
  1092. are unchanged: surface revision remains 32 and the latest migration remains
  1093. 026.
  1094. - Restored the real stdio smoke test on clean stores after capability
  1095. registration became fail-closed.
  1096. - Documented when and how to run the isolated two-agent smoke flow on Unix and
  1097. Windows, including its `LIVE E2E RESULT: PASS` completion signal.
  1098. - Added semantic cards for structured `kind` messages in the Graph conversation
  1099. drawer, with distinct read-receipt and handoff lifecycle treatments instead
  1100. of raw JSON.
  1101. - Synchronized `pyproject.toml`, `uv.lock`, and release commands at version
  1102. 0.1.5.
  1103. ### 0.1.4
  1104. Dashboard, observability, and coordination-guidance release. The MCP guidance
  1105. contract advances to surface revision 32; the database schema is unchanged and
  1106. the latest migration remains 026.
  1107. - Added detailed and compact activity-based agent graph modes, profile colours,
  1108. live status badges, richer relationship context, and graph conversations.
  1109. - Added an event timeline, expanded event and handoff filters, message detail
  1110. hydration, workspace display names, and catalog import/export workflows.
  1111. - Improved dashboard views for agents, approvals, communication, events,
  1112. guardrails, handoffs, messages, policies, and workspaces.
  1113. - Extended observability APIs and repositories with message lookup, filtered
  1114. handoff/event queries, and bucketed event timeline data.
  1115. - Completed PyPI project URLs, keywords, and supported-Python classifiers, with
  1116. a focused metadata regression test.
  1117. - Added contributor and security policies, structured GitHub issue forms, and
  1118. a dedicated documentation-assets location for product screenshots.
  1119. - Clarified that agents follow the role and communication profile returned by
  1120. `agent_whoami` unless the user supplies a task-scoped override, without
  1121. bypassing platform governance.
  1122. - Defined handoffs as the required, traceable mechanism for executable work,
  1123. broadcasts as shared alignment or information fan-out, and direct messages
  1124. as status, clarification, and informal coordination channels.
  1125. - Rewrote this README against the current CLI, transport/authentication model,
  1126. dashboard, 43/46-tool surface, seven routing strategies, message retention,
  1127. governance features, verification/DAG workflows, 34-table schema, 29-code
  1128. error catalog, operations, testing, and limitations.
  1129. - Synchronized `pyproject.toml` and the root project entry in `uv.lock` at
  1130. version 0.1.4, and aligned the package/dashboard license label with the
  1131. addendum that is actually included in `LICENSE`.
  1132. - Removed tracked runtime SQLite databases and added ignore coverage for
  1133. database files and journal/WAL/SHM sidecars.
  1134. - Verified release archives contain the dashboard and migrations without
  1135. runtime SQLite databases or sidecars.
  1136. ### 0.1.2
  1137. - Documentation-accuracy sweep at surface revision 31.
  1138. - Corrected pre-flight, monitoring, heartbeat, inbox, trace, policy, HITL,
  1139. artifact-audience, and target-grammar documentation.
  1140. - Kept 12 deep reference resources versioned and reduced the resident cuttable
  1141. surface to about 26.3k characters.
  1142. - Corrected the token-reduction gate to include experimental-surface growth.
  1143. ### 0.1.1
  1144. - Hardened authenticated self-only identity/session rules and permission
  1145. checks.
  1146. - Added permission-gated workspace paths, shared view, health, and memory.
  1147. - Added configurable aggregate metrics telemetry.
  1148. ### 0.1.0
  1149. - Added ephemeral remote-monitor tokens and read-only monitor endpoints.
  1150. - Added attachable policies, communication presets, guardrail/group
  1151. administration, enriched agent graph cards, and loopback trust hardening.
  1152. - Made memory a registration-time experimental MCP surface.
  1153. ### 0.0.x
  1154. - Built the MCP reference-resource system, HTTP hub, live dashboard, inbox
  1155. receipts, semantic search, monitoring guidance, and dashboard observability
  1156. waves.
  1157. ## Automatic inventory revalidation
  1158. Authenticated host inventory publications automatically revalidate configured
  1159. runtime connections. Core version changes and changes to unrelated installations
  1160. do not require repeating agent setup when the selected installation evidence and
  1161. runtime contract remain identical. Original bindings, permissions, grants, and
  1162. running-session identities are preserved. Fresh inventory is still required.
  1163. The Execution log shows `INVENTORY_REVALIDATED` or `INVENTORY_REVIEW_REQUIRED` per
  1164. connection. Changed or missing installations, changed execution capabilities, or
  1165. missing historical evidence require review. Legacy embedded connections can use
  1166. their retained, digest-verified local installation record as the baseline.
  1167. Version observations survive a Core upgrade only for the exact same host source
  1168. and platform; current Core still evaluates runtime support and containment.
  1169. ## Remote machine approval and connection status
  1170. Remote approvals are scoped to the agent and its registered Connector machine
  1171. identity (`connector_id` / `executor_id`), not its hostname or IP address.
  1172. **Settings → Remote machine policy** defaults to **Require approval** when
  1173. another machine requests the same agent. The operator can select **Deny another
  1174. machine** or **Accept and revoke previous machine** instead. The first machine
  1175. always requires approval. A reviewed replacement revokes the previous machine's
  1176. endpoints, grants, binding tickets and session capabilities atomically.
  1177. Automatic replacement retains the approved harness preferences and the original
  1178. grant expiry and consumed action count. It cannot widen tool access or renew an
  1179. exhausted authorization. Ambiguous prior connections require manual review.
  1180. Connector onboarding is asynchronous: after submitting the request, the CLI
  1181. returns and its daemon completes the connection after approval, including after
  1182. a daemon restart. No operator key is needed on the remote computer. Use
  1183. `okto-nexus-connector status` (or `--json status`) for each configured connection's
  1184. current state. The authenticated `GET /v1/connections/status` endpoint reports
  1185. only connections belonging to the calling agent, without credentials or paths.
  1186. ## License
  1187. Copyright 2026 Okto Labs.
  1188. Okto Nexus is distributed under the Elastic License 2.0 together with the
  1189. project's SaaS, competing-service, internal-use, and branding addendum. It
  1190. permits internal and qualifying single-tenant use and prohibits the specified
  1191. multi-tenant, white-label/OEM, competing, and large-scale internal-platform
  1192. uses; applicable notices and attribution remain required.
  1193. Read the complete
  1194. [LICENSE](https://github.com/OktoLabsAI/okto-nexus/blob/main/LICENSE) before use
  1195. or redistribution. It is also included in the source distribution and served
  1196. by the running hub at `GET /api/v1/license`.
  1197. ## Global harness MCPs
  1198. See [global harness MCP inheritance](docs/global-mcps.md) for global defaults,
  1199. agent/harness overrides and local/remote host behavior.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.