Skip to main content

Orchestrator to Runtime

Once the orchestrator receives a user message, it needs to get that message to the user's ZeroClaw runtime and return the response.

In plain language, this page explains the handoff from "the main backend accepted the request" to "the user's agent runtime did the work and answered back."

This is the core request and response path for every user interaction with agents.

The Webhook Flow​

Orchestrator to Runtime Flow
Click diagram to zoom

Step By Step​

1
Step 1

Ensure the runtime exists

Before forwarding anything, the orchestrator checks that the user's runtime exists and is ready. If the runtime does not exist yet, the platform creates it and the operator begins reconciling the child resources. If the runtime exists but is not yet verified, the orchestrator waits.



In plain terms, this is the "make sure the user's agent is actually there before sending work to it" step.



This is why the first message after account creation may take a few extra seconds.

2
Step 2

Broadcast status

As soon as the orchestrator starts processing, it emits realtime events such as agent busy/typing state over Socket.IO so the mobile app can show immediate feedback.

3
Step 3

Call the webhook

The orchestrator calls the runtime via an internal cluster network call. Runtime pods are not accessible from the public internet.

The important idea is simple: users never talk to the runtime pod directly. The backend always stands in the middle.

The request includes the user's message plus optional agent_id when the orchestrator routes to a specific workspace agent. In the normal path, system_prompt is no longer forwarded because ZeroClaw reads native delegate-agent identity from config.toml.

4
Step 4

Process the agent work

Inside the ZeroClaw pod, several things happen:

  • Prompt and runtime context are loaded
  • The configured LLM provider is called
  • Tool calls may be executed inside the runtime
  • The final response is returned to the orchestrator as JSON containing a response field
5
Step 5

Handle the response

When the orchestrator receives the runtime response, it:

  • Clears the typing/busy state
  • Persists the user message and agent reply in PostgreSQL
  • Broadcasts message.new events over Socket.IO
  • Returns the API response to the caller

The current implementation persists messages before broadcasting them.

MCP Tool Calls​

During agent processing, ZeroClaw may call tools exposed by the orchestrator's embedded MCP server. This is how agents access platform capabilities such as push notifications, user data, and conversation history without holding separate application credentials:

MCP Tool Call Flow
Click diagram to zoom

Every MCP tool call is authenticated with scoped internal tokens tied to the calling user and workspace.

If you are new to MCP, the practical meaning is "the runtime can ask the backend to do platform-owned actions without carrying raw app credentials itself."

Why Orchestrator Calls ZeroClaw via /webhook​

In this context, the webhook is the private HTTP contract between the orchestrator and one user's ZeroClaw runtime.

Here, "webhook" simply means the internal HTTP endpoint that the backend uses to talk to the runtime.

The orchestrator sends one JSON request to the runtime's /webhook endpoint.

That request includes the user message, the X-Session-Id header for conversation continuity, and optional agent_id when routing to a specific workspace agent.

That contract is intentionally small:

  • one request in
  • one JSON response out
  • no public runtime endpoint to secure
  • no streaming lifecycle between orchestrator and runtime
  • easy inspection with ordinary HTTP logs and tooling

The orchestrator resolves the runtime over internal networking, posts the request, and reads the response. If the runtime returns a non-200 status, the orchestrator treats the call as failed.

As the runtime evolves, this transport may change. For the current platform, a synchronous internal /webhook is the simplest contract that matches how ZeroClaw is deployed and how the orchestrator routes chat traffic.

What's Next​

See Real-time Events to understand how Socket.IO and Redis deliver events to connected clients.