OktoLabs Docs Get started
All use cases
USE CASE · NEXUS IN PRODUCTION WORKSPACE · NEXUS-BROWNFIELD-HANDOFF-DEMO

Two Agents. One Approval Gate.

Nexus enforces structural separation between claiming work, gating it for human approval, and recovering from a dead session. The dashboard below reproduces that run in the current Nexus interface, with local demo states for the surrounding product screens.

View the repo ↗
0
Handoffs created
0
Handoffs completed
0
Rejections (claim race skipped)
0
Avg. seconds to human approval
Okto Nexus / Graph
LIVE
Loading dashboard snapshot…

Interactive product demo with local mock data. Explore entities, conversations, handoffs and workspace health without credentials or a connection to the original workspace.

01 · PROBLEM

Four ways multi-agent work quietly breaks.

AI agents are good at doing work. They're not naturally good at not doing the same work twice, not touching something risky without asking, or remembering what happened after a session dies.

01

Two Agents Can Claim the Same Task

Without a single-winner rule, both proceed, and now there are two conflicting implementations of the same thing.

02

Risky Actions Ship Because Nobody Was Asked

A schema change, a delete, a deploy: if nothing pauses it for a human, "the agent decided to" is the whole audit trail.

03

A Policy Nobody Enforces Is a Suggestion

A dependency rule that only warns doesn't stop an agent from building against a schema that doesn't exist yet.

04

Coordination Context Dies With the Session

Kill an agent mid-task and whoever picks it up next is starting from zero, re-reading everything a human has to re-explain.

02 · ARCHITECTURE

One handoff. A structural gate.

Every step below is a real mechanism in the coordination layer, not a convention either agent has to remember to follow.

How the gated migration actually moved
Schema Agent handoff_create

SQL + reasoning placed directly in the description.

Gate require_approval intercepts

The call never creates the handoff; it returns pending_approval instead.

Queue Pending approval

SQL and Schema Agent's reasoning sit visible for a human.

Operator Human approves / rejects

Approve replays the original call with a one-shot bypass; the handoff is now OPEN.

Race Claim race: atomic single winner

An atomic conditional update guarantees exactly one winner; the loser gets a clean rejection.

Skipped this run, see caveat below
API Agent Dependency gate

An early claim on a dependent handoff is refused with DEPENDENCY_NOT_MET, proven live.

Signal handoff_complete fires handoff.unblocked

Completion clears the dependency for whatever was waiting on it.

API Agent Session killed

The connection is fully terminated mid-build: process exit, not idle.

Fresh session handoff_get + event_get replay

Zero prior context, reconstructs the claimed state and full history from Nexus's own record.

Close-out Derived metrics

A script reads the event log for claim latency, rejection count, time-to-approval; there's no built-in metrics tool for this.

03 · HOW IT WORKS

Eight stages, one real run.

Grounded in this workspace's actual event log, the same sequence the dashboard above is built from.

  1. STAGE0

    Setup

    Operator attaches require_approval to Schema Agent's handoff_create; confirms feature_dag is on.

    PUT /api/v1/agents/schema-agent/policies
  2. STAGE1

    Propose (gated)

    Schema Agent calls handoff_create for the migration, SQL in the description, intercepted automatically into the approvals queue.

    handoff_create → pending_approval
  3. STAGE2

    Human approves

    Operator approves in the dashboard; handoff_create replays with a one-shot bypass. The migration handoff is now OPEN.

    apr_73e55614ac184b188fe7d8c19b3e90e5 · 118s
  4. STAGE3

    Claim race

    Deliberately skipped this run: the migration's target was scoped to role:api, leaving only api-agent eligible. Not a Nexus limitation, a consequence of how the proposal was scoped.

    handoff_claim
  5. STAGE4

    Early-claim denial

    Proven live with a separate blocker/dependent pair, since the real migration had already completed by this stage. A genuine DEPENDENCY_NOT_MET response.

    hof_c958ebd1196a4fce8279b5f4c89cefa9 → hof_ef44c4977d104cb688c5ab2758557af4
  6. STAGE5

    Apply + complete

    The claim winner applies the migration for real against the target app's Postgres DB, then calls handoff_complete.

    RateLimitEvent model + migration.sql on disk
  7. STAGE6

    Unblock + build

    handoff.unblocked fires; API Agent claims its handoff and builds the admin metrics endpoint against the now-real schema.

    GET /api/admin/metrics
  8. STAGE7

    Session kill + recovery

    API Agent's session is terminated entirely mid-build. A brand-new connection with zero prior context reconstructs state from Nexus's own record and finishes the task.

    handoff_get + event_get/event_cursor
  9. STAGE8

    Close-out

    A close-out script pulls handoff.claimed/handoff.rejected/approval.requested/approval.granted timestamps and derives claim latency, rejection count, time-to-approval.

    docs/prompts/closeout.py
04 · REFERENCE BUILD

Two agents. One operator.

Two separate MCP connections, separate credentials (not one identity switching hats), plus the human who holds the approval gate.

SA
Schema Agent
Proposer
Can do
  • Proposes the migration via handoff_create, SQL in the description
  • Races to claim it once approved
  • Applies the migration for real
Cannot do
  • Approve its own handoff_create: a human-only decision once the policy intercepts it
AA
API Agent
Dependent builder
Can do
  • Proposes its own dependent handoff with depends_on
  • Races to claim the migration
  • Builds the endpoint once unblocked
Cannot do
  • handoff_claim its own handoff while the migration isn't COMPLETED: DEPENDENCY_NOT_MET
OP
Operator
Human, dashboard
Can do
  • Pre-attaches require_approval to handoff_create
  • Approves or rejects the pending proposal
Cannot do
  • N/A: dashboard/REST-only role, no MCP identity of its own beyond the reserved rejection-notice agent
05 · QUICKSTART

Install it. Bind the gate.

The real install commands, plus what actually gets configured in the dashboard's Policies screen before either agent connects.

  1. 01

    Install and serve

    > pip install "okto-nexus[serve]"
  2. 02

    Start the bus

    > okto-nexus serve
    okto-nexus init is not a real subcommand; serve alone bootstraps the data dir on first run.
  3. 03

    Create the policy in the dashboard

    Open Policies → New policy, name it, and add one governance rule: handoff_create requires approval.

  4. 04

    Bind it, connect two identities

    Bind the policy to schema-agent as a global, latest-mode rule, then connect Schema Agent and API Agent with separate MCP configs, same pattern as Pulse's Builder/Validator split.

Dashboard · Policies → New policy
Namerequire-approval-on-migration-handoffs
Governance rulehandoff_create→require_approval
Bound toschema-agent
Modelatest

require_approval only applies to handoff_create/message_create, not artifact_put, which is why the gate sits on proposing the migration, not the later SQL write.

Both agents work through the same MCP surface. The tool calls this workflow actually makes:

ToolUsed for
handoff_createSchema Agent proposes the migration handoff (SQL in the description): the call the require_approval policy intercepts; API Agent proposes its dependent handoff with depends_on
handoff_claimBoth agents race on the now-approved migration handoff; API Agent's claim on its own dependent handoff (denied until unblocked)
handoff_completeCloses the migration handoff after it's applied, firing handoff.unblocked
handoff_getRecovered session reads current handoff state after a killed session
event_get / event_cursorRecovered session replays history; close-out script derives timing metrics
artifact_putOptional: the winner can record the applied SQL for the record; not policy-gated
06 · WHY IT MATTERS

Enforced by structure, not by instruction.

Policy-Gated Creation

A bound require_approval policy intercepts handoff_create automatically: the agent never chooses to ask, Nexus decides to hold it.

Atomic Single-Winner Claims

An atomic conditional update guarantees exactly one winner on a claim, with a clean typed rejection for the loser.

Dependency Gating (DAG)

depends_on structurally blocks a claim, not just a comment saying "do this after that": DEPENDENCY_NOT_MET, proven live.

Durable Recovery

A killed session's replacement reconstructs claimed state and full history entirely from Nexus's own durable record.

Run it locally. See the gate work.

Free to run on your own machine. No account required.

Run it locally View product surfaces