docs
// Execution Management (EEM)

EEM Overview

EEM is the agent role that runs tool calls instead of token calls. It rides the same CurveZMQ mesh as EIM, picks up infrastructure invocations as lease-bound jobs, and streams progress back to the conversation. Same router, same audit log, separate concern.

Overview

Reasoning and execution belong on separate agents. A language model running on an existing EIM node produces the plan and the tool calls. The EEM node, deployed on or adjacent to the target infrastructure, runs them. The router brokers every message between the two; neither side talks to the other directly.

Ownership model: EEM is always project-owned. The platform provides routing, credential encryption (via the router-mandatory EREBINE_COMPLETION_ENCRYPTION_KEY), and audit logging. The platform does not provide sandboxing, safe execution guarantees, or remediation for EEM actions. If a user deploys a EEM, they accept full ownership of what the model runs.

EIM vs EEM

EIM and EEM are the two agent roles in the Erebine mesh. They share an enrollment mechanism, transport (CurveZMQ + MessagePack), and audit path, but they own different halves of an agentic loop.

ConcernEIM (Inference)EEM (Execution)
Output Tokens, embeddings, tool-call plans. Side effects on infrastructure.
Runtime vLLM with model weights; GPU required. Static Swift binary; no GPU, no model weights.
API key scope inference execution
Workspace binding Per-project endpoint manifest. workspace_agent_bindings per operational workspace.
Ownership Platform-managed; router brokers placement. Project-owned; operator accepts what the model runs.

Architecture

The EEM architecture follows the same mesh pattern as EIM. The router sits at the center, coordinating between the inference agent (EIM) and the execution agent (EEM) via CurveZMQ with MessagePack serialization. 

flowchart LR
    Frontend --> Router
    Router --> Scope["Scope / Manifest / Rate-Limit Middleware"]
    Scope --> Approval["Approval Gate"]
    Approval --> EIM["EIM (Inference)"]
    Approval --> EEM["EEM (Execution)"]
    EIM --> Audit["Audit Log (PostgreSQL)"]
    EEM --> Audit
    EEM -. SSE .-> Frontend
    Approval -. SSE .-> Frontend
Request flow: scope check, approval gate, dispatch to EIM or EEM, audit log, SSE back to the frontend.

The flow for a tool execution request is:

  1. The inference model (on EIM) emits a tool_calls response with x_exec: true.
  2. The router validates scope, rate limits, and approval policy.
  3. If the tool is destructive or irreversible, the router triggers a human-in-the-loop approval gate.
  4. The router dispatches the tool call to the appropriate EEM agent.
  5. The EEM executes the tool and returns results.
  6. The router forwards results to the inference model for synthesis.
  7. The final response streams to the frontend via SSE.

EEM requires no GPU, no model weights, and no vLLM. It is a single static Swift binary in a minimal container image, enrolling over HTTPS via the join-key JWT mechanism and establishing a CurveZMQ data plane with the router.

Agents vs Workspaces

A single EEM agent serves many workspaces. Each workspace is a named operational-scope binding (e.g. kubernetes-prod, openstack-platform, docker-fleet). Workspaces come in two kinds:

KindDescriptionEEM binding
chat Knowledge workspaces for conversations, documents, and research. None, no tool execution.
operational Infrastructure workspaces with scoped credentials and tool access. Bound to one or more EEM agents via workspace_agent_bindings.

Chats live under workspaces. Memories, artifacts, and learnings are workspace-scoped. Promotion from chat to operational is supported (via PUT /:project_id/v1/workspaces/:id with kind=operational); demotion is not.

Capabilities

The router-side surface that EEM agents consume includes:

  • Exec API, tool catalog, invocation lifecycle, execution records, and raw output retrieval under /:project_id/v1/exec/*.
  • Approval engine, human-in-the-loop approval gates with SLA and escalation chains.
  • Internal research, research hop available to EEM-routed invocations under POST /:project_id/v1/internal/research.
  • Chat templates, prompt template management under /:project_id/v1/chat-templates/* with platform, project, and workspace scope layers.
  • User preferences, picker history and pinned items under /:project_id/v1/user/preferences.
  • Rate limiting, four-layer rate limiter (agent, workspace, tool, user) backed by the configured cache (Redis in production, in-memory by default via EREBINE_CACHE_BACKEND).
  • Webhook events, 14 exec.* event types for external integrations (see webhooks).
  • erectl commands, see the erectl exec CLI reference for the registered subcommand surface.

API Surface

All EEM-specific endpoints require the execution API-key scope. A key with only inference scope cannot enable x_exec: true in requests, the router returns 403 scope_insufficient.

FamilyPath prefixScope
Exec (tools, invocations, executions, approvals) /:project_id/v1/exec/* execution
Chat templates /:project_id/v1/chat-templates/* inference (read) / management (write)
User preferences /:project_id/v1/user/preferences inference
Learnings /:project_id/v1/exec/learnings execution
Context /:project_id/v1/exec/context execution
Internal research POST /:project_id/v1/internal/research execution

Security Model

  • CurveZMQ encryption, every ZMQ frame between router and EEM is encrypted with Curve25519.
  • Manifest-as-allowlist, the router rejects tool names the EEM did not declare in its capability manifest (see error codes for the rejection codes emitted by the exec dispatch path).
  • Approval gates, destructive and irreversible operations require human approval by default.
  • Four-layer rate limiting, per-agent, per-workspace, per-tool, and per-user caps prevent runaway execution.
  • Audit logging, invocation rows are written to execution_audit_log, with foreign keys linking the associated approval and execution records.
  • Scope enforcement, API key scopes are checked at the middleware level before any handler code runs. The exec dispatch path applies a two-tier check: an umbrella execution scope at the middleware mount, then a per-tool scope evaluated by the exec scope validator before the call reaches the EEM.
  • Enrollment refresh, /v1/enroll/refresh verifies the EEM token signature inline (no middleware) using a grace-window check; all other EEM-facing routes sit behind the scope middleware stack.

Getting Started

To begin working with EEM execution management:

  1. Ensure your API key has the execution scope enabled.
  2. Browse available tools with erectl exec tools or GET /:project_id/v1/exec/tools.
  3. Invoke a tool with erectl exec invoke --workspace <wid> --tool kubectl.get --args '{"resource":"pods","namespace":"default"}' or POST /:project_id/v1/exec/invocations.
  4. Monitor execution with erectl exec watch <invocation-id> or poll GET /:project_id/v1/exec/invocations/:id.
  5. Configure approval policies per workspace to gate destructive operations.