@stigmer/runner

Embeddable Temporal worker for the Stigmer AI agent platform. The runner executes agent sessions and workflow executions — driving the Cursor and native (deep-agent) harnesses, orchestrating MCP servers, and reporting status and artifacts back to the Stigmer backend.

It is the single runtime behind three surfaces:

• the CLI daemon (stigmer up) running agents locally,
• cloud deployments (Kubernetes / sandbox) running managed executions, and
• the desktop app, which embeds the runner as a subprocess to run sessions on the user's own machine.

This document is the operational reference for the package: how it runs, what it needs, and every environment variable that configures it. You should not need to read config.ts or main.ts to operate or embed the runner.

You usually don't start the runner by hand. stigmer up runs it for local agent execution, and the desktop app embeds it automatically. Invoke the stigmer-runner binary directly only for advanced operation or embedding — which is what this document covers.

The deep manager-mode IPC protocol (see Manager mode), the desktop-vs-web embedding walkthrough, and the SDK-level RunnerAdapter / executionTarget surfaces are documented separately — see Related documentation.

Install and build

The runner is a workspace package in the Stigmer monorepo. Build it from the repo root:

make build-runner

This runs npm run build in backend/services/runner (tsc -p tsconfig.build.json) and then writes a build fingerprint (see The stale-build guard). The compiled output lands in dist/, with a stigmer-runner CLI entry point at dist/main.js.

Requires Node.js >= 20.

The slim embedding artifact

The plain dist/ resolves its dependencies from node_modules at runtime — ~508 MB unpacked, which is unshippable inside a desktop app (#170). For embedding, build the slim artifact:

make build-runner-slim          # or: npm run build:slim

This produces dist-slim/: a tree-shaken esbuild bundle of the whole runner (main.js), a build-time-prebuilt Temporal workflow bundle, and a staged node_modules containing only the packages that genuinely cannot be bundled (the platform-pruned Temporal native bridge, @cursor/sdk and its native binaries, jq-wasm) — ~85 MB per platform. node dist-slim/main.js accepts the same modes, environment variables, and IPC protocol as dist/main.js. See scripts/bundle-slim.mjs for the full layout, scripts/verify-slim-artifact.mjs for the boot verification that gates releases, and the embedding guide for how apps stage it.

Why the slim bundle is CommonJS, not ESM. The runner's auth correctness depends on a deliberate module load order: it installs the fetch + HTTP/2 interceptors first, then lazily loads @cursor/sdk and @connectrpc/connect-node (via dynamic import()) so the interceptors are in place before those packages capture globalThis.fetch / snapshot the node:http2 ESM facade. An ESM esbuild bundle destroys this — it hoists every external import to the top of the output and evaluates them before any code runs, freezing the node:http2 facade and capturing the original fetch before install, which silently breaks proxy auth on the authenticated path (this was the regression in #170). A CJS bundle preserves the source's lazy evaluation order, so the dynamic-import boundary keeps both interceptors correct. The meta package.json deliberately omits "type": "module" so node main.js runs as CommonJS — do not add it back, and do not flip format to "esm" in bundle-slim.mjs. The boot guard assertHttp2ConnectPatched() plus the authenticated check in verify-slim-artifact.mjs fail loudly if this is ever reverted.

The slim build is also published to npm as @stigmer/runner-slim (with per-platform @stigmer/runner-slim-<platform> support packages) alongside the full @stigmer/runner package on every release.

Run modes

The runner has two run modes, selected by the STIGMER_RUNNER_MODE environment variable. Do not confuse the run mode (process topology) with the execution location (MODE=local|cloud) or the transport (STIGMER_PROXY_ENDPOINT) — those are independent axes covered in Execution location vs transport.

Static mode

Static mode creates a single Temporal Worker that polls one task queue and runs until it receives SIGTERM / SIGINT. This is the right mode when the set of work is fixed at startup (a daemon or a pod dedicated to a queue).

As a library:

import { createStigmerRunner } from "@stigmer/runner";

const runner = await createStigmerRunner({
  taskQueue: "stigmer_runner",
  temporalAddress: "localhost:7233",
  stigmerEndpoint: "http://localhost:7234",
});

process.on("SIGTERM", () => runner.shutdown());
await runner.start(); // blocks until shutdown

The stigmer-runner CLI runs this mode by default, reading its configuration from the environment.

Manager mode

Manager mode keeps a single shared Temporal connection and a single set of activities, then spins Workers up and down on demand — one per session (session:{sessionId}) and one per workflow execution (wfexec:{executionId}). This is what the desktop app needs: it adds and removes Workers as the user opens and closes sessions, without restarting the process.

As a library:

import { createStigmerRunnerManager } from "@stigmer/runner";

const manager = await createStigmerRunnerManager({
  temporalAddress: "localhost:7233",
  stigmerEndpoint: "http://localhost:7234",
});

await manager.addSession("ses_abc123");
// ... later
await manager.removeSession("ses_abc123");
await manager.shutdown();

As a subprocess, the host launches stigmer-runner with STIGMER_RUNNER_MODE=manager and drives it over a line-delimited JSON protocol on stdin/stdout (addSession, removeSession, addWorkflowExecution, updateToken, shutdown). The protocol surface is intentionally small and is specified in detail elsewhere — see Related documentation.

A note for embedders: OpenTelemetry

When you embed the runner as a library (createStigmerRunner / createStigmerRunnerManager), the factory does not initialize OpenTelemetry — tracing and metrics mutate global state, which the embedding process should own. The factory still wires the Temporal OTel interceptor internally when OTEL_EXPORTER_OTLP_ENDPOINT is set, but you must initialize the tracer/meter providers yourself if you want spans and metrics exported. The stigmer-runner CLI initializes OTel for you in static mode.

Execution location vs transport

Two settings are easy to conflate but are deliberately independent:

• MODE — execution location. Where the agent runs and whose filesystem it sees. local allows local-path workspaces on the host filesystem; cloud runs in a server-provisioned sandbox (git-only).
• STIGMER_PROXY_ENDPOINT — transport. How credentials and artifacts move. When set, the runner routes Cursor SDK traffic through the Stigmer proxy and pushes artifacts through it, instead of talking to providers and storage directly.

These are orthogonal. The desktop runner is the canonical case where they diverge: it executes locally (MODE=local, so local-path workspaces work) yet still routes Cursor traffic and artifact uploads through the proxy. Coupling the two — forcing "proxy implies cloud" — is exactly what previously broke local-path sessions, which is why the env path (MODE) and both library factories (executionMode) treat them separately.

Library factories — executionMode. Both createStigmerRunner and createStigmerRunnerManager accept an optional executionMode: "local" | "cloud" that sets execution location independently of proxy transport. When omitted, the static createStigmerRunner derives it for backward compatibility (proxy ⇒ cloud, otherwise local); the manager defaults to local. Set executionMode: "local" together with proxyEndpoint to express the desktop case — local execution with proxy transport.

Credential modes

The transport setting drives two credential modes:

• Direct mode (local / OSS): you provide CURSOR_API_KEY directly (for the Cursor harness); STIGMER_TOKEN is optional because a local Stigmer server has no auth. STIGMER_PROXY_ENDPOINT is unset.
• Proxy mode (cloud / managed runners): STIGMER_PROXY_ENDPOINT and STIGMER_TOKEN are required. You do not supply CURSOR_API_KEY — the proxy validates your token and injects the real Cursor key upstream. The runner sets CURSOR_BACKEND_URL / CURSOR_API_BASE_URL to the proxy endpoint automatically; these are runner-managed, not configuration you set.

Required infrastructure

In local/direct mode, only Temporal and the Stigmer backend are required, and both default to localhost.

The stale-build guard

The runner runs from compiled dist/ output. A stale dist/ — source changed but not rebuilt — silently runs old code, which has historically cost hours of debugging (structured-output failures, naming mismatches, env-resolution regressions).

To prevent this, npm run build writes dist/.build-fingerprint: a JSON file with a SHA-256 hash of all src/**/*.ts files (excluding node_modules and __tests__), plus a build timestamp and file count. At startup, checkBuildFreshness() recomputes the hash and compares it. On mismatch, the runner prints a clear error and exits with code 78:

!!! STALE RUNNER BUILD — REFUSING TO START !!!
    dist/ was built at <timestamp> (hash <hash>)
    src/ has changed since (current hash <hash>)

    Run 'make build-runner' or 'make desktop-dev' to rebuild.

The check is skipped gracefully when the fingerprint file is absent — for example under tsx (npm run start), in CI, or on a first build — so it never blocks development workflows that run from source.

Environment variable reference

All configuration is environment-driven. Names and defaults below are verified against src/config.ts, src/shared/artifact-storage.ts, src/claimcheck/config.ts, src/otel.ts, and the LLM/registry activities. "Applies to" indicates the run mode, execution location, or credential mode a variable is relevant to.

Core configuration

Artifact storage

Claim-check (large Temporal payloads)

The claim-check codec offloads oversized Temporal payloads to artifact storage and passes a reference instead.

Credentials and providers

Observability

Advanced and debug

These tune internal behavior or support testing. Most operators never set them.

Related documentation

• Manager-mode IPC protocol — the line-delimited JSON command/response contract and its versioned handshake (current protocol version 1). A short pointer also lives at docs/ipc-protocol.md; the code definition is src/ipc-protocol.ts.
• Embedding integration guide — building a desktop client (local execution) and a web client (cloud execution), including the per-audience configuration each one passes.
• SDK RunnerAdapter and executionTarget — the local-execution surfaces in @stigmer/react and @stigmer/sdk. The embedding guide covers them today; a dedicated SDK reference is forthcoming.
• Public API — src/index.ts exports createStigmerRunner and createStigmerRunnerManager with typed options and inline examples.