Skip to documentation
Documentation

External harness Code Mode

Opt into search and execute for your external agent's Keiki tools.

External harnesses receive individual MCP tools by default. Code Mode is an opt-in alternative: your model discovers tools with search, then runs JavaScript calling them through execute. It uses this agent's per-turn catalog, not the dashboard API. Your model loop stays in your application. Hermes is unchanged and uses direct tools.

Enable Code Mode

Set harness_config.toolMode to "codemode" through the existing developer config API. For example, using a key scoped to the agent:

Terminal
curl -X PATCH https://onkeiki.com/api/v1/developer/config \
  -H "Authorization: Bearer $KEIKI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "harness": "external",
    "harness_config": { "mode": "inbox", "toolMode": "codemode" }
  }'

This example configures inbox delivery. For push delivery, preserve your mode and dispatchUrl when setting the connection. The dashboard's authenticated PUT /api/webapp/agents/:id/harness/connection endpoint also accepts { "mode": "inbox", "toolMode": "codemode" }, and partner deployments accept the same harness_config in the agent spec. From the dashboard, ask the copilot to configure the external connection with toolMode: "codemode"; it uses the existing connection API. There is no separate Code Mode toggle required in your harness process.

The deployment must configure CODEMODE_MCP_WORKER_URL, CODEMODE_MCP_SECRET, and a platform base URL. Even with the opt-in, missing configuration falls back to direct tools and direct-tool instructions. Explicit requests to an unconfigured Code Mode endpoint return 503.

What your harness sees

Use turn.keiki.mcpUrl with the turn token, as usual. When enabled and configured, the URL selects /api/v1/harness/mcp/codemode. The AI SDK, Flue, and Eve adapters use that dispatched URL automatically. The MCP tool list contains:

  • search: discover tool signatures and descriptions.
  • execute: run an async JavaScript arrow function against keiki.*.
  • Direct delivery tools such as reply and ask_question, where available for the channel. These are excluded from execute; call them directly to reach the contact.

For example, search for conversation_search, then execute:

JavaScript
async () => {
  return await keiki.conversation_search({ : "appointment" });
}

The catalog includes enabled built-ins, authored tools, MCP preset tools, installed capability tools, and the tools exposed by attached skills. Existing permissions, channel availability, steering, delivery tracking, and turn spans still apply. Tools defined only inside your own harness process are not in Keiki's catalog and cannot be called through execute. Keep exposing those to your model separately.

Names and limits

Tools live at the keiki root. Non-identifier names are sanitized into JavaScript-safe aliases: customer-lookup can become customer_lookup. Numeric suffixes resolve collisions, including with the keiki.search helper. Search returns the executable path and signature; aliased hits also include tool, the original upstream name used for dispatch. Exact executable paths take precedence over original-name matches.

An execute program runs for at most 120 seconds and makes at most 100 tool calls. It has no direct network access; use the discovered tools. Results above 60,000 serialized characters fail rather than being stored or truncated. Return a narrower result. Delivery tools remain direct calls, outside these execute limits.

Switch back to direct tools

Set harness_config.toolMode to "direct" through the same API, preserving the rest of your connection settings. Omitting the option from a replacement connection also uses direct tools. Only "direct" and "codemode" are valid values. Subsequent turns receive /api/v1/harness/mcp and list the individual tools.