Runtime & CLI

Symbiote Engine divides execution utilities between browser-compatible APIs and server-side runtimes. It ships with a command-line interface (CLI) for validation and local execution, along with a lightweight synchronization server for development.

Package Entrypoints #

The library provides two primary entry points to organize browser-safe logic separately from Node.js-only operations:

symbiote-engine/browser: Exposes core data models (Graph, Executor, and registry utilities) that can build, connect, and execute graphs inside a browser. To prevent browser bundle crashes, this module excludes exported file helpers, server, implementation queues, and local providers.
symbiote-engine (Node entrypoint): Adds server-side capabilities, including persistence wrappers, in-memory task queues, local audio providers, and media rendering wrappers.

Browser Caveats & Bundler Compatibility

Note these limitations. Do not assume every browser consumer or bundler is supported:

The downloadGraph API requires Blob, URL, and document.
The FocusController uses location and events at call time.
Persistence.js contains dormant dynamic Node file imports.

CLI Commands #

The package installs the symbiote-engine command-line executable. It allows developers to run workflows, validate graph definitions, list registered nodes, and inspect workflow structures.

Usage & Syntax #

# Execute a workflow graph using local handlers
symbiote-engine run <workflow.json> [--pack video] [--handlers ./custom] [--secrets ./secrets.json] [--verbose] [--json]

# Validate graph definitions (does not perform complete schema validation)
symbiote-engine validate <workflow.json> [--pack video] [--handlers ./custom] [--json]

# List all registered node types in the current environment
symbiote-engine list [--pack video] [--handlers ./custom] [--json]

# Inspect a workflow file without running it
symbiote-engine inspect <workflow.json> [--json]

# Launch the WebSocket synchronization server for a workflow
symbiote-engine serve <workflow.json> [--port 3100] [--handlers ./custom] [--verbose]

CLI & Parameter Constraints

Secrets: The --secrets argument expects a path. It otherwise attempts ./secrets.json, but either loaded object is passed under an Executor option the handlers do not consume. It does not provide automated secrets injection or secure storage.
Packs: The --pack flag is mapped specifically to the built-in video-pack. Collections like packs/ai, packs/flow, and packs/transform are handler collections, not CLI --pack names. To load other local JS handlers dynamically, use the --handlers <dir> flag instead.
Partial JSON Error Output: When --json is enabled, syntax errors, missing file errors, or severe runtime exceptions may throw standard process errors, resulting in partial or incomplete JSON outputs in the terminal stream.

GraphServer Connection #

The GraphServer subpath provides a factory to synchronize graph modifications between a local workspace and front-end editor components.

Programmatic Server Initialization #

Because it is not part of the root export, GraphServer must be imported directly from its module path. It requires the ws peer dependency (version 8 or higher) to be resolved in the host environment.

import { createServer } from 'symbiote-engine/GraphServer.js';

const serverInstance = await createServer({
  port: 3100,
  workflowFile: './workflows/main.workflow.json',
  handlersDir: './handlers',
  watchFiles: true,
  verbose: true
});

// Close the HTTP/WS server and watchers when done
await serverInstance.close();

Development Security & Protocol Boundaries

The GraphServer is a development primitive and does not represent a production-ready application server. Consider these security limits:

No Authentication: The server contains no credentials verification, TLS encryption, or authorization policies.
Wildcard Permissions: It serves wildcard CORS headers (*) and permits WebSocket connections from any origin.
Remote Mutation: Clients connecting to the WebSocket have complete access to modify the graph (adding nodes, removing nodes, connecting sockets) and trigger execution on the host machine.
Watcher Bug: When file watching is enabled, the server watcher parses the JSON to an object, and then passes that object to a function that calls JSON.parse, which results in a failing reload, not just extra overhead.

Reusable Handler Packs #

Packs allow developers to bundle and share custom node handler definitions.

Video-Pack: The built-in video-pack automatically registers metadata descriptors for audio-visual operations upon import. However, many descriptors fall back to a generic projection behavior (processing parameters and matching outputs) without executing real media manipulation. Users must register custom media drivers to perform concrete video editing or synthesis tasks.
Custom Handlers: Reusable JavaScript handlers can be hotloaded from a designated folder at launch. These files must match the *.handler.js suffix and register their operational logic with the engine's node registry.