lightspeed README

The project's README from github.com/smartcomputer-ai/lightspeed. As one markdown file: README.md.

Lightspeed logo

Lightspeed

Run thousands of agents. Efficient, durable, auditable.

Lightspeed is open-source infrastructure for running managed agent fleets as durable workflows.

"Managed agents" is an emerging pattern that separates the core agent loops from the VM or sandbox they use. Agents survive restarts, can run for months, and stay cheap when idle. When they need an operating system, they borrow a real machine for as long as the task requires.

Lightspeed software factory with a fleet of specialized bots and an implementer supervising a sub-agent

Lightspeed's Rust core runs on Temporal today and stores production data in Postgres with optional S3. The frontend is TypeScript and React.

Why Lightspeed?

Lightspeed aims for the capability of Claude Code, Codex, and OpenClaw without requiring one operating system per agent.

Most frontier harnesses live inside a guest OS, which makes them difficult to scale and secure. Hence the emerging pattern to "separate the harness from compute" or the brain and hands split. This is especially useful in enterprises with more stringent supervision and scaling requirements.

So, in Lightspeed, the harness (the agent loop, context, and session state) runs as a lightweight durable workflow. Shells, code execution, and full filesystems run on machines attached only when needed. One worker can therefore manage hundreds of agents.

Comparison: traditional infrastructure runs one agent per full VM, while Lightspeed packs many durable agents into one worker and attaches VMs or sandboxes only when needed

What you can build with Lightspeed:

Quick start

You need Rust with edition 2024 support, Node.js 24 or newer, and Docker with Compose. Then start the complete local product:

./dev.sh

You can set the LLM API keys directly in the UI. But you can also set them via environment variable:

cp .env.example .env
# Set OPENAI_API_KEY or ANTHROPIC_API_KEY in .env
# Then restart ./dev.sh

When the readiness checks pass in the CLI, open http://localhost:5173/app/ and sign in with the development account printed by the launcher. The defaults are [email protected] and lightspeed-dev-password.

The launcher installs dependencies, starts local infrastructure and application processes, applies migrations, and waits until the product is ready.

For other development profiles, service addresses, resets, and live tests, see the local development guide. See Environment variables for environment variables.

Features

Lightspeed covers the table stakes of a modern agent harness. Everything below works today.

Models & providers

Agent capabilities

Bots & channels

Durability & scale

Borrowed compute

Security & auth

Design

In Lightspeed, every agent is driven by an event-sourced, deterministic core. The runtime replays the session log, decides the next step, and emits effect intents that adapters execute against LLM providers and tools. The core itself performs no I/O, which makes it a natural fit for durable workflow engines.

Two more decisions make this practical inside a workflow engine:

  1. Minimal provider abstraction. The core extracts only the facts needed to make decisions; provider-native data stays opaque and blob-backed.
  2. Offloading to CAS. Large payloads live in content-addressed storage, keeping workflow histories small. Blobs nothing reaches any more are collected after a grace period, so deleting sessions frees their storage.

The architecture walkthrough introduces the system. Continue with the agent loop and durability, context and storage, and tools and controller workflows to understand better how everything works and fits together.

Lightspeed architecture: clients reach a session workflow holding the deterministic core inside Temporal; thin effect intents and result refs cross to activities that talk to LLM providers and borrowed compute; both sides share a session log and CAS

Development checks

cargo test
npm run check

See Testing and evaluation for focused checks, replay coverage, live-test prerequisites, and model evaluations.

Documentation

Preview the Starlight manual with npm run dev:docs.

Contributing

See CONTRIBUTING.md

License

Apache 2.0

lightspeed (smartcomputer-ai/lightspeed)

durable-execution
Searching Database…

264 ·GitHub
Lightspeed
What is this?Lightspeed is open-source infrastructure for running fleets of AI agents as durable workflows: agent sessions survive restarts, can run for weeks to months, and stay cheap when idle, borrowing a real machine only when a task needs one.
Is it a library I embed in my app, or a service I deploy and use?A full self-hosted product, not a library: a Rust core runs on Temporal, production data lives in Postgres (with optional S3), and there is a TypeScript and React frontend you drive through the UI or a JSON-RPC API.
How do I get a local instance running?Install Rust with edition 2024 support, Node.js 24+, and Docker with Compose, then run the launcher: it installs dependencies, starts the local infrastructure and app processes, applies migrations, and prints a development sign-in ([email protected]). Set your LLM API keys in the UI or via environment variables.
Which LLM providers and keys do I need?OpenAI and Anthropic work out of the box — set the keys in the UI or via environment variables. OpenAI-compatible servers like OpenRouter, DeepSeek, vLLM, and Ollama are also supported, each with its own endpoint and credential, plus automatic prompt caching.
Do agents get a real shell and filesystem out of the box?No — without a machine attached, agents work through a virtual file system and provider-hosted web access. Shells, code execution, and full filesystems only exist on attached environments: an existing machine, an Incus-provisioned VM, or any host running the lightspeed-envd daemon.
What do people actually build with it?Long-lived agent fleets: personal assistants for thousands of users without an idle VM per user, autonomous software factories that build and critique features for weeks, on-call ops agents that investigate alerts, and research agents supervising long-running experiments.
Can I run it as one self-hosted deployment for many users?Yes — it is built for that: isolate tenants in universes on a single deployment or run dedicated per-tenant ones, and one backend binary can run every role in a single process or scale roles independently across Temporal workers.
How are my API keys and secrets handled?Credentials are encrypted at rest with automatic OAuth token refresh, and environments or jobs receive secrets via credential injection without exposing them to the model. Deployments are multi-tenant by default, isolated in universes.
Can sessions really run for months and survive restarts?Yes — sessions last weeks to months and survive restarts. While a run is active you can cancel or steer it or queue the next message, and sessions can be forked or cloned to branch off stored history.
Does it support MCP servers and sub-agents?Both. MCP connects local or remote servers with API keys or OAuth, with tool calls handled by the model provider or by Lightspeed itself, including progressive discovery through tool search. Sub-agents let an agent delegate to supervised children with configurable profiles and limits.
Can bots act on their own, without a human prompting them?Yes — bots are always-on agents that wake up for scheduled tasks, incoming webhooks, data changes, or chat messages. They can manage their own schedules, webhooks, and pollers, coordinate with other bots, and you can chat with them via Telegram and WhatsApp.
Why is the deterministic, event-sourced core a big deal?The core replays the session log to decide each next step and performs no I/O itself, which is exactly what makes it fit a durable workflow engine like Temporal. Large payloads go to content-addressed storage, keeping workflow histories small.
What are similar projects?evenfire, hermes-agent, hive, ruflo, brigade, DeskcommCRM, openfang, ARTEX
Which topics is it in?event-sourcing, durable-execution, rust-lang, whatsapp, vps, bot, s3, agent-harness, telegram, autonomous-agents, workflow, agent-orchestration
Creator
smartcomputer-ai
Size
17.4 MB
Stars
264
Updated
CommitOct 18Releasev0.4.0Oct 04
Age
8mo
Commits · 90 Days