Skip to content

Docs · Internals

Four ways to run an agent, one test suite

The nexus SDK ships four adapters behind the agent contract: Claude Code, a native harness on any OpenAI-compatible endpoint, Codex and a generic ACP client. This page shows how they differ and how one conformance suite keeps them honest.

What it does

claude_code wraps the Claude Code CLI. native runs its own tool loop on a model endpoint over HTTP. codex drives codex app-server. acp speaks the Agent Client Protocol to any agent you can launch.

Each adapter is compiled behind its own cargo feature (provider-native, provider-codex, provider-acp). Only claude_code is always built.

The same conformance suite and the same security suite are replayed against every adapter, with fake executables standing in for real services.

The diagram

The four provider adapters and their test kitFlow diagram. The agent contract is implemented by four adapters: claude_code, native, codex and acp. claude_code talks to the claude command line, native to an OpenAI-compatible chat completions endpoint, codex to codex app-server and acp to any ACP agent. Native, Codex and ACP processes are started through a single launcher with an allow-listed environment. A test kit holds a conformance suite of 25 scenarios, a security suite of 5 scenarios, fake executables and an in-memory scripted provider; the suites are replayed against the adapters.implemented byMCP stdio serversstand in forreplayed againstreplayed againstAgent contractAgentProvider, AgentSession, AgentEventtransport::spawn::isolated_commandsingle launcher under providers/ (checked by a test):allow-listed environment, process group,no secret on argvclaude_code (always compiled)ClaudeCodeProvider, facade on InteractiveClientoptional remote instance over SSHnative (feature provider-native)NativeProvider: tool loop, MCP tools only, budgetson a ModelEndpoint: HTTP + SSE, quirks, price tablecodex (feature provider-codex)codex app-server, JSON-RPC over stdioone process per sessionacp (feature provider-acp)generic Agent Client Protocol clientone process per sessionclaude CLIstream-jsonOpenAI-compatible/chat/completionscodex app-serverany ACP agent(command in config)Conformance suite25 scenarios, same suite for every providerabsent capability: its fallback is checkedSecurity suite, 5 mandatory scenariosunknown policy refused, env isolation,no secret on argv, no credential in errors,tool outside profile refusedFake executablesfake_claude, fake_openai + fake_mcp,fake_codex, fake_acpScriptedProviderin-memory provider, replays transcripts

Drag to move. Pinch, Ctrl + wheel or the + and - keys to zoom; arrow keys to move; 0 to fit; double-click to fit. Select a node to light up its links.

Zoom outZoom inFull screen
Redrawn from the verified diagram nexus-agent-providers (verified 2026-10-06). Labels are the names used in the code.
Text description of the diagram

Flow diagram. The agent contract is implemented by four adapters: claude_code, native, codex and acp. claude_code talks to the claude command line, native to an OpenAI-compatible chat completions endpoint, codex to codex app-server and acp to any ACP agent. Native, Codex and ACP processes are started through a single launcher with an allow-listed environment. A test kit holds a conformance suite of 25 scenarios, a security suite of 5 scenarios, fake executables and an in-memory scripted provider; the suites are replayed against the adapters.

Guided reading

  1. Step 1. claude_code

    ClaudeCodeProvider is a facade over the interactive client. One pump per session reads messages and control requests, projects them to events and routes them to the active turn or to the out-of-turn channel. An instance can also run the same flow over SSH. Features that need the local machine (a per-session MCP server, local directories, a mode without confirmation) are refused rather than ignored.

  2. Step 2. native

    NativeProvider composes a model endpoint with a tool loop: one turn is several model and tool round trips, parallel tool calls run concurrently, and budgets bound the turn. Tools come from MCP servers only.

  3. Step 3. The model endpoint

    OpenAiEndpoint speaks chat completions over HTTP and server-sent events. Server quirks (DeepSeek, Ollama, vLLM, llama-server, NIM) are flags and presets. A tool-calling probe checks a model before use, and the price table returns nothing rather than 0 when a price is unknown. Endpoint URLs are validated: https outside loopback, no credentials in the URL, internal address ranges refused after DNS resolution, no redirects.

  4. Step 4. codex and acp

    CodexProvider drives codex app-server over JSON-RPC on stdio, one process per session. AcpProvider is a generic Agent Client Protocol client whose command comes from configuration. Both start through the single launcher: allow-listed environment, process group, no secret on the command line. Closing a session kills the process and its descendants.

  5. Step 5. The conformance suite

    The suite drives a session through 25 scenarios and checks the stream invariants. When a provider lacks a capability, the scenario is not skipped: the written fallback is verified. A capability that is declared but never staged is refused.

  6. Step 6. The security suite

    Five mandatory scenarios that no capability can switch off: an unknown policy is refused, the environment is isolated, no secret reaches the command line, errors carry no credential, and a tool outside the profile is refused.

  7. Step 7. Fakes first

    Each adapter is built against a fake executable (fake_claude, fake_openai with fake_mcp, fake_codex, fake_acp). For Codex and ACP, the fakes follow a schema and transcripts taken from the public protocol documentation.

Why it is built this way

The fake is the specification

A new provider delivers a fake executable and a transcript before any transport code, so the expected behaviour is written down as something that runs.

One launcher

A test searches the sources for any direct process start under the providers directory and fails if it finds one, so a new adapter cannot bypass the isolation rules.

The security suite found real defects

Its first run showed Codex and ACP starting without a dedicated home directory, and a configuration debug output that printed environment variables. Both were fixed.

Third-party adapters stay behind a gate

They are off by default and add no dependency. The registry refuses any third-party instance until the host attests the security gate, which cannot be undone once set.

What is not established

  • No real Codex, no real ACP agent and no real model endpoint has been exercised by these suites: each is seen through its fake executable. The Codex adapter requires codex app-server 0.130.0 or later.