Runtime
startRuntime options and the session-first HTTP route table.
import { startRuntime } from "@nylorun/runtime/core";
const runtime = await startRuntime({
sqlitePath: "./nylorun.sqlite",
serverToken: process.env.NYLORUN_SERVER_KEY!,
executors: [],
port: 8787,
});
await runtime.close();Runtime is an independent SQLite HTTP host. It consumes @nylorun/harness/run
and @nylorun/core/contracts. It does not depend on @nylorun/agents.
Generated projects do not import this package; @nylorun/cli starts
@nylorun/runtime/server.
Requires Node 24+. Default address: http://127.0.0.1:8787.
startRuntime
| Option | Type | Required | Description |
|---|---|---|---|
sqlitePath | string | Yes | SQLite file. Keep WAL/journal beside it. |
serverToken | string | Yes | Application bearer (≥16 characters). |
executors | scoped { token, agentId, implementationVersion }[] | Yes | Process-only startup scopes. Empty is valid; register more with PUT /v1/executors. |
model | ModelProvider | No | Optional provider. Omitted without useHostModel: scriptedModel(). |
useHostModel | boolean | No | Read the host vault at call time. |
leaseMs | number | No | Executor claim lease. |
vaultKek / vaultKekPath | key or path | No | Vault encryption. null disables env/file lookup. |
sandbox | { backend?, root? } | No | auto (default), microsandbox, or virtual. |
port / hostname | number / string | No | Listen options. Default port 8787. |
close() drains the host. It does not close application tools.
Removed from this family: httpModel, localSessions, in-process Runtime,
serveAgents, openSession, and the AG-UI route.
HTTP routes
Authoritative contract: HOST_CONTRACT.md.
Unauthenticated
| Method | Path | Response |
|---|---|---|
| GET | /health | { status: "ok", service: "oss-runtime", version?, scopeId?, pid? } |
| GET | /ready | { status: ready|not_ready, service, checks } — SQLite and scheduler, not provider connectivity |
Application bearer (NYLORUN_SERVER_KEY)
| Method | Path | Notes |
|---|---|---|
| PUT | /v1/agents/:agentId | requestId, complete manifest, implementationVersion, optional pluginRoots |
| GET | /v1/agents | Saved definitions |
| PUT | /v1/sessions/:sessionId | agentId, trusted ownerUserId, optional info, vaultIds, credentialSelections |
| GET | /v1/sessions/:sessionId | Status, waits, MCP snapshot, pending actions |
| GET | /v1/sessions | Optional ?agentId= |
| POST | /v1/sessions/:sessionId/commands | SessionCommand |
| GET | /v1/sessions/:sessionId/items | ?cursor= and optional ?agent= (delegationId or path) |
| GET | /v1/sessions/:sessionId/events | SSE; cursor or Last-Event-ID |
| POST/GET/DELETE | /v1/vaults and /v1/vaults/:vaultId/credentials | Metadata only on read |
| GET/PUT | /v1/host/model | Never returns the secret |
| PUT | /v1/host/model/selection | Switch active provider/model |
| GET | /v1/host/providers | Configured providers |
| GET | /v1/host/models | Public catalog |
| GET | /v1/host/sandbox | Selected sandbox backend |
| PUT/GET | /v1/executors | Register/list; tokens never listed |
| DELETE | /v1/executors/:agentId | 409 if from NYLORUN_EXECUTORS_JSON |
Executor bearer
| Method | Path | Notes |
|---|---|---|
| GET | /v1/executors/connect | SSE work_available |
| GET | /v1/actions | Pending actions for scoped agentId |
| POST | /v1/actions/:actionId/claim | { requestId, implementationVersion } |
| POST | /v1/actions/:actionId/heartbeat | Lease renewal |
| POST | /v1/sessions/:id/commands | action_result only |
Executor credentials cannot call vault, host model, or executor admin routes.
A stored manifestHash is ignored. Subscribe before discovery; notifications
never authorize execution.
Command idempotency keys bind to canonical request content within a session;
requestId is excluded from comparison.
Guides: Deploy, Host Runtime.