Executors

Connect your implementations to Runtime.

The local CLI does this for you: nylorun dev and nylorun serve register manifests and connect a scoped executor. Custom hosts call connectAgents.

import { connectAgents } from "@nylorun/agents";
import { agents } from "./index.js";

const connection = connectAgents({
  agents,
  runtime: {
    url: process.env.NYLORUN_RUNTIME_URL,
    key: process.env.NYLORUN_EXECUTOR_KEY,
  },
});

await connection.ready;

Your tools and hooks run in that connected executor. Runtime persists the session and offers actions. The executor claims that work, runs your implementation, and returns a result.

runtime.key is a scoped executor credential, not the server key. Each executor token is limited to agentId (and implementationVersion on registration). A manifestHash stored on an existing token is ignored. In-flight actions stay claimable after the registered digest changes. Clients cannot broaden that agent scope. The local CLI writes separate server and executor secrets to .nylorun/local-credentials.json (mode 0600).

implementationVersion defaults from NYLORUN_IMPLEMENTATION_VERSION, then dev. Claim requests send { requestId, implementationVersion } only.

connection.ready settles after authenticated SSE is established and initial discovery succeeds. connection.close() aborts subscriptions and leases. Running user code receives an AbortSignal.

What the executor runs

Claimed actions have kind tool or hook. A hook action runs every capability registered at that { at, scope } point in one round trip. The executor looks up the matching capability implementation and runs it.

Sandbox tools are not claimed by your executor; Runtime runs them.

On this path:

• Invalid tool arguments become tool.invalid-input (no engine details: { phase, issues } object).
• context.progress is a no-op.
• sleep and waitFor return inspectable deferred outcomes. Automatic timer and event wakeups are not implemented.
• Interrupted customer tool work becomes uncertain. It is not automatically repeated.
• An expired hook claim is offered again. Keep side effects in tools.

Subscribe before discovery; rediscover after reconnect. work_available notifications never authorize execution.

Credentials and process

Keep server and executor keys out of the browser. Studio's local proxy holds the server credential and excludes executor claims and results.

Assign an explicit implementationVersion when you change a versioned implementation. See Deploy: executors for registration on a running host.

Next step