car-runtime

Node.js bindings for Common Agent Runtime — a deterministic execution layer for AI agents. Models propose; the runtime validates and executes.

As of v0.8, this package is a thin daemon client: every method proxies to a singleton car-server daemon over WebSocket. The binary that runs the inference, holds the per-session memory graph, and dispatches tools is shipped alongside the .node module in this same package — start it once per host before using the bindings.

Install

npm install car-runtime

The package's install script downloads the matching native binary for your platform from car-releases. Both the .node module and the car-server daemon binary are included. Supported platforms: macOS (14+) arm64/x64, Linux x64/arm64 glibc, Windows x64.

Start the daemon

# Foreground (Ctrl-C to stop). Default port 9100; auth on by default.
npx --package=car-runtime car-server

# Or background:
npx --package=car-runtime car-server &

On macOS, the SwiftUI menubar host (car-host) launches the daemon automatically; install with car-host install (registers a launchd LaunchAgent so it comes up at login).

Quickstart

import { CarRuntime, executeProposal } from 'car-runtime';

const rt = new CarRuntime();   // lazy-connects to ws://127.0.0.1:9100/

// Register tools + policies. These calls proxy to the daemon's
// per-session runtime and persist for the lifetime of this WS
// connection.
await rt.registerTool('shell');
await rt.registerPolicy('no_rm', 'deny_tool_param', 'shell', 'command', 'rm -rf');

// Verify before executing — pure static analysis on the daemon side.
const proposal = JSON.stringify({
  actions: [{
    id: 'a1',
    type: 'tool_call',
    tool: 'shell',
    parameters: { command: 'ls' },
    dependencies: [],
  }],
});

const check = JSON.parse(await rt.verifyProposal(proposal));
if (!check.valid) throw new Error(`invalid: ${JSON.stringify(check.issues)}`);

// Execute with a JS tool callback. The callback runs in this Node
// process; the daemon's WsToolExecutor calls back over the same WS
// when an action needs to dispatch a tool. Proxied via
// `register_handler("tools.execute", ...)` on the underlying
// DaemonClient (phase 7.4).
const result = await executeProposal(rt, proposal, async (callJson) => {
  const { tool, params } = JSON.parse(callJson);
  // Dispatch to your tool implementation.
  return JSON.stringify({ stdout: 'ok' });
});

Full API reference lives in index.d.ts. High-level docs and examples: https://github.com/Parslee-ai/car-releases

Environment variables

• CAR_RUNTIME_SKIP_DOWNLOAD=1 — bypass the install-time download. Place the binary in the package directory yourself.
• CAR_RUNTIME_DOWNLOAD_BASE=<url> — override the download origin (e.g. internal mirror). Binary filename is appended.

License

Free for any use including commercial; free to redistribute unmodified. Modification, reverse engineering, and derivative works are not permitted. See LICENSE for the full text. Copyright © 2026 Parslee AI.