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:
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 againstkeiki.*.- Direct delivery tools such as
replyandask_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:
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.