Skip to main content
The Polycore runner is the execution half of the system. It is a long-running Node.js process deployed in your infrastructure, close to the databases and APIs it is allowed to reach.

It executes

The runner validates inputs, resolves local credentials, calls your downstream systems, and returns structured results.

It does not govern

Caller authentication, routing, human approval, and audit persistence live in the control plane. The runner accepts signed dispatches from that plane.

​
One runner, one target

Each runner is bound to one Polycore project and one environment.
  • The project identifies the product or system whose catalog the runner advertises.
  • The environment identifies the concrete call target, such as dev, staging, or prod.
  • Separate runners for separate environments preserve network and credential isolation.
The environment is fixed during enrollment. A request cannot tell a production runner to swap to a different secret bundle.

​
What the runner loads

The deployed runner combines built-in, customer-authored, and optional surfaces:

Built-in queries

Generic, read-only capability families supplied by the runner SDK (@polycore/runner), currently including Postgres and Firestore. Firestore can additionally be granted approval-gated generic mutations.

Customer actions

Named TypeScript operations from the actions/ directory. Each action has typed input and output, a hazard, and an explicit secret declaration.

Project context

A concise, committed document that explains customer-specific domain terms and data conventions to the agent for this project.

Delegated workloads

An optional sandbox configuration advertises code.execute with hazard unknown. It is disabled unless explicitly configured.
The runner advertises capability metadata and optional project context when it connects. It does not advertise secret values.

​
Configuration and runtime bindings

Structural configuration is committed as polycore.json. Deployment supplies identity, enrollment credentials, datastore coordinates, and secrets.
This split is deliberate:
  • Code defines authority. Query families, actions, action schemas, and project context are reviewed in your repository.
  • Deployment defines identity. The process is bound to one project and one enrolled environment.
  • Your secret system provides values. Credentials arrive through workload identity or deployment-time secret injection.
See Runner configuration for the supported fields.

​
Credential resolution

On GCP, Firestore can use Application Default Credentials. The runner process receives a service account, and GCP IAM decides which project and operations it can access. No service-account key file is required in the normal hosted path.
Avoid committing values under the optional secrets field. The file format supports local evaluation, but production secrets should be supplied by your deployment and secret-management system.

​
Connection lifecycle

1

Load and validate

The runner parses polycore.json, resolves file paths relative to the config, discovers actions, and validates the complete capability registry.
2

Resolve runtime identity

Environment variables bind the process to a project, control-plane runner registration, and enabled datastore query families.
3

Dial the control plane

The runner opens a persistent outbound WebSocket and enrolls with its provisioned identity.
4

Advertise the catalog

The runner sends capability names, kinds, hazards, input and output schemas, and optional project context. Secret values are excluded.
5

Serve signed dispatches

For each valid dispatch, the runner checks the signature and schema, runs the capability, and returns either a structured result or a structured failure.
6

Reconnect

Application-level heartbeats detect stale sessions. The runner reconnects with exponential backoff and advertises its current catalog again.

​
Registration lifecycle

The dashboard groups registrations with the same slug as one runner namespace, but each environment still has a separate runner ID and credential set. Use the same slug for every deployment of one logical runner. Capability calls always use <runner>/<capability> and never infer a default runner. The Integrations inspector shows every project environment as Online, Offline, Never connected, or Not configured.
  • Add an environment issues a new one-time credential set for that exact environment. Store it in that environment’s secret manager before closing the result.
  • Reissue credentials revokes an offline or never-connected registration before issuing its replacement. The old credentials stop working.
  • Remove from an environment revokes only that registration and closes its active connection. Other environments remain independent.
  • Remove from all environments is a separate danger-zone operation that atomically revokes the namespace’s active registrations.
Revocation preserves runner identity in historical approvals and capability invocations. A revoked registration disappears from the active directory, and the same slug can later be enrolled again for that environment.
Runner credentials are shown once and cannot be recovered from Polycore. If they are lost, revoke and reissue the affected environment registration.

​
Hosting requirements

The runner needs a Linux environment suitable for a persistent worker:
  • Node.js 22 or the Polycore runner container.
  • Outbound TLS access to the Polycore control plane.
  • Network access to the specific downstream systems it serves.
  • A workload identity or secret-manager path for scoped credentials.
  • A process supervisor or container restart policy.
  • For managed rollouts, a restricted health probe that is ready only while the runner has an active control-plane session.
For GCP integrations, Polycore maintains a Container-Optimized OS managed instance group preset in polycore/runner-gcp. Its health endpoint accepts no dispatches and is reachable only by Google Cloud health probes. During early access, we adapt and deploy it with your team.
Treat runner availability as part of the target environment. If the production runner is offline, Polycore should report the operation as unavailable, not silently reroute it to staging or another credential set.