Connect executors

An executor is a process that claims tool and hook actions for one agent id. The local CLI provisions tokens automatically. Custom hosts register them on the running Runtime.

import { connectAgents } from "@nylorun/agents";

const connection = connectAgents({
  agents,
  implementationVersion: process.env.NYLORUN_IMPLEMENTATION_VERSION ?? "app-1",
  runtime: {
    url: process.env.NYLORUN_RUNTIME_URL,
    key: process.env.NYLORUN_EXECUTOR_KEY,
  },
  onError: console.error,
});

await connection.ready;
await connection.close();

Register or rotate credentials with the application bearer:

PUT /v1/executors

Body: { executors: [{ agentId, implementationVersion, token }] }. Optional manifestHash on the record is stored and listed, but ignored for authorization. Claim identity is agentId only. Tokens must be at least 16 characters and must differ from the server key and from each other.

• Unchanged registration is idempotent and keeps open streams.
• Rotation ends the replaced token's streams.
• GET /v1/executors lists summaries (never tokens).
• DELETE /v1/executors/:agentId removes a registration. Startup scopes from NYLORUN_EXECUTORS_JSON are 409 on delete.

NYLORUN_EXECUTORS_JSON is an array of { token, agentId, implementationVersion } applied to that process only. It is not persisted.

Executor credentials authorize GET /v1/executors/connect, action discovery, claims, heartbeats, and action_result commands. They cannot call vault, host model, or executor admin routes.

See Run: executors for claim behavior and Runtime HTTP.

Next step