Lightspeed is a powerful agent harness built for durable workflow engines. It allows you to run complex agents and sub-agents that survive restarts, run for months, and scale to thousands, without needing a dedicated VM for each one.
Temporal is fully supported today; others are coming soon: Restate, Inngest, Hatchet, AWS Step Functions, etc. The core is written in Rust. The production data backend is Postgres and optional S3.
The goal of Lightspeed is to build as powerful an agent as Claude Code, Codex, or OpenClaw, but running outside operating systems, thus separating the harness from compute. Plus, making this tenable for workflow engines.
Concretely, that means the harness—the agent loop, context management, session state—runs as a lightweight durable workflow, while OS-level work (shells, code execution, full file systems) happens on machines the agent attaches to only when a task needs them. The result: thousands of agents managed by a single worker node.
Frontier agent harnesses like Claude Code, Codex, OpenCode, or OpenClaw are designed to run inside a guest OS and need an entire OS for themselves, which makes them difficult to scale and secure. Hence the emerging pattern to "separate the harness from compute", and to run agents inside workflow engines for durability. This is especially interesting in enterprise or shared deployments, where you cannot easily co-locate agents on the same VM.
But most agent SDKs are not designed for workflow engines: they do not separate the deterministic core from effects such as LLM or tool calls, and they pass too much data between the core workflow logic and the effectful "tasks" or "activities"—e.g. the entire chat history back and forth—which bloats workflow histories.
One caveat we take seriously: frontier models are optimized to the hilt (via RL) assuming they control a full POSIX-compatible OS, so an agent with just MCPs and provider-native tools will underperform one with a real machine. Bridging that gap is a central goal of Lightspeed: agents can borrow compute (dedicated VMs via a bridge daemon, ad-hoc sandboxes, delegated coding-agent jobs) while the harness stays outside the OS.
What you can build with Lightspeed:
- An insanely scalable OpenClaw-style personal assistant: thousands of users, very low cost (besides tokens)
- A fully autonomous software factory: a fleet of agents that build, test, and critique your next feature — and keep running for weeks
- Research agents that spin up compute for long-running experiments, stay live for days, and supervise progress
- ...and much more!
You need Rust with edition 2024 support, Node.js 24 or newer, and Docker with Compose. Then configure at least one model provider and start the complete local product:
cp .env.example .env
# Set OPENAI_API_KEY or ANTHROPIC_API_KEY in .env
./dev.shWhen the readiness checks pass, open
http://localhost:5173/app/ and sign in with the
development account printed by the launcher. The defaults are
admin@lightspeed.dev and lightspeed-dev-password.
That is the supported happy path. The launcher installs npm dependencies when needed, starts the local infrastructure and editable application processes, applies migrations, and waits until the product is ready.
For focused profiles, lifecycle commands, provider-free startup, connector configuration, manual runtime roles, local service addresses, resets, and live test setup, see the development environment guide. Environment variables are documented separately in docs/variables.md.
What constitutes an "agent harness" is a rapidly expanding set of table-stakes features. Lightspeed is not 1.0 yet, but it is far enough along to try: everything checked below works today (see Quick start), and the unchecked items are actively in flight:
Models & providers
- OpenAI and Anthropic, provider-native: reasoning traces, native compaction, advanced tool configs, provider tools, files and images, OAuth login, multiple API keys
- OpenAI-compatible providers via universe-scoped endpoint records: OpenRouter, DeepSeek, vLLM, Ollama, and similar Chat Completions or Responses servers can each carry their own URL, credential, non-secret headers, and admitted API kinds without putting transport configuration in a session
Agent capabilities
- Virtual file system: dedicated
vfs_*tools read and edit linked snapshots/workspaces without an OS attached - Web access: fetch, search, and extract tools
- Skills, automatically cataloged and loaded from linked VFS roots
- Hosted MCP, with universe-configured API-key and OAuth identities shared by every session selecting that MCP server id
- Flexible prompt & instruction configuration
- Sub-agents (aka "fleets"): agents that start and manage other agents
- Agent profiles: reusable session setups, shared across clients and fleets; a profile can activate an existing environment or provision a fresh one per session
Durability & scale
- Long-running agents: sessions that last weeks to months and survive restarts
- Active-run control: cancel a run (in-flight model and tool calls are aborted, no farewell turn), steer it with a message the model sees at its next turn, or queue the next message behind it — all admitted live, not after the run
- Session fork & clone: cheap forks of a running agent's full state, straight from the event-sourced log
- Managed sessions and workflow-backed tools: trusted workflow controllers can create sessions with immutable tool bindings, durable emissions, keyed completions, deadlines, and cancellation
- Eval harness for regression-testing agent and tool workflows
- Timers, schedules, wake-ups
Borrowed compute
- Dedicated VMs, connected as universe environment instances that
sessions use through event-sourced active environment state; model discovery
and selection is a separate, default-off
selectionToolsgrant. Ordinary file and process tools always operate on the selected environment and never on linked VFS content. The in-repo stateless Incus provider supplies durable full-VM provisioning, explicit takeover of existing VMs, on-demand envd routes, and pause/stop power control; real Incus deployment still requires node certificates, an immutable image, and provider policy configuration - Environment power states and idle policy: environments can be paused, suspended, or stopped by intent, staged idle policies power them down from the daemon's own idle clock, and any powered-down environment wakes transparently on its next use
- Provider-owned jobs for long-running work: downloads, experiments, and delegated coding-agent runs with optional session/run supervision. Jobs are an advanced, default-off environment grant and appear as model tools when the environment feature grants them; live availability is checked when invoked
- Ad-hoc sandboxes
Security & auth
- Encrypted secrets: AEAD-encrypted secret store, plus an OAuth token broker with automatic refresh
- Credential injection: secrets reach environments and jobs without ever being exposed to the model
Interfaces
- Typed JSON-RPC API: committed schema contract, generated TypeScript client
- Configurator MCP: a configurable universe API surface as generated tools over Streamable HTTP
- CLI to connect to running agent sessions
The generated JSON-RPC API reference is derived from the same Rust manifest and schemas that drive OpenRPC, the TypeScript client, and Configurator MCP tool descriptions.
At the heart of every agent is a carefully engineered state machine that manages what goes into the context window of the LLM.
In Lightspeed, that state machine is an event-sourced, deterministic core: it replays a session's event log into state, decides the next step, and emits effect intents that runtime adapters execute against real LLM providers and tools. The core itself performs no I/O, which is exactly the shape that plays well with durable workflow engines.
Two more decisions make this practical inside a workflow engine:
- Minimal provider abstraction. We extract only the information needed to decide and branch inside the deterministic core; provider-native data stays opaque and blob-backed, instead of being converted into a fake universal LLM message model.
- Offloading to CAS. All data not directly needed by the workflow logic goes to content-addressed storage, so the payloads passed between workflow and activities are extremely thin and the workflow history stays small.
Lightspeed's plugin infrastructure lets external workflows add durable tools to an agent. A plugin can create and manage a session, provide tools backed by its own workflows, and rely on Lightspeed to deliver calls, wait for results, handle timeouts, and cancel work. Plugins stay independent from the core session worker.
The full design walk-through is in docs/design.md.
cargo test
npm run check- Design
- Development environment
- Environment variables
- Universes, tenant isolation, and gateway authentication
- JSON-RPC API reference
- Build and release
- Roadmap and design decisions
See CONTRIBUTING.md