Lightspeed documentation

Lightspeed runs long-lived agents as durable workflows. Sessions retain their conversation and execution state across worker restarts, and agents can use tools, work with persistent files, and react to events. When a task needs an operating system, the session selects an execution environment that supplies the machine.

The distinction between the durable session and its compute runs through the product. You can start with a model and a conversation, add a workspace and a reusable profile, then connect machines or build bots as the work requires.

The Software Factory demo: a session investigates a flaky test, uses tools, and delegates an audit. The conversation and its work stay together in one place.

Try Lightspeed

Begin with Core concepts to understand sessions, runs, profiles, bots, workspaces, and environments. Then follow Get started with Lightspeed to choose a prebuilt Linux release or a local source checkout and configure a model.

Build your first agent is a worked example: create a release-editor profile, give it source material, and inspect the persistent file it produces. It also shows how to continue a session and reuse the profile for another conversation.

Use an existing installation

Use the universe and account supplied by your operator. The model setup instructions and first-agent walkthrough apply to an existing installation too. Managing those resources requires a universe owner/admin or platform administrator account.

The usage guides build on that first working agent:

• Sessions and runs: continue work, queue or steer tasks, inspect results, and manage history.
• Models and credentials: connect providers, select model routes, and understand credential defaults.
• Profiles and instructions: make a reusable setup and apply changes deliberately.
• Workspaces and skills: share persistent files, source project instructions, and add a review skill.
• Tools and MCP: grant built-in tools, connect external services, and configure approvals.
• Bots and triggers: create an ongoing agent, deliver events, and inspect its activity.
• Sub-agents and federation: delegate bounded tasks or coordinate independent bots.
• Chat channels: connect Telegram or WhatsApp and pair conversations with a bot.

When an agent needs a shell or a machine’s files, read Environments. Connect a machine with Bring your own compute or configure managed provisioning with Incus VMs. Then use Using environments and Processes and jobs for selection and execution. Credentials, power and cleanup, and networking and ingress explain the access and lifecycle choices around that work.

Deploy Lightspeed

The deployment overview explains the runtime, Platform, databases, Temporal, and the public/private network boundary. Self-host Lightspeed installs the full web product using release images built from a pinned source revision and existing durable infrastructure.

Continue with these deployment guides:

• Authentication and access: configure gateway modes, create accounts, assign roles, and issue client keys.
• Multitenancy: understand universe isolation, shared infrastructure, and tenant retirement.
• Configuration: connect service settings, storage, secrets, and public/private URLs.
• Operations: observe useful work, scale roles, and manage retention.
• Upgrades and recovery: prepare a complete recovery set and update a coherent release.
• Troubleshooting: trace a failure across authentication, workers, models, compute, and chat delivery.

The environment-variable reference provides the exact names, defaults, and requirements for each component.

Build with Lightspeed

Start with an integration path:

• API and TypeScript: submit a task, retry safely, follow events, and retrieve its result.
• Configurator MCP: connect an MCP client and manage resources in its authorized universe.
• Workflow tools: connect an agent to durable receivers, started workflows, and lifecycle controllers.
• Custom tools and model providers: choose an extension boundary and implement compiled capabilities when needed.
• Environment providers: supply managed compute through the public controller and data protocol.
• Channel connectors: add a chat transport through account discovery, ingress, and connector activities.

The JSON-RPC reference and workflow contract provide exact operation and payload details.

Understand how it works

The design walkthrough develops the system from a deterministic agent loop into durable sessions, shared storage, and independent controllers:

• Architecture: the layers, their ownership, and why the session harness is separate from compute.
• Agent loop and durability: admission, committed events, effects, the two histories, replay, and rollover.
• Context and storage: provider-native content, prompt assembly and caching, compaction, VFS, and blob retention.
• Tools and controller workflows: tool identity, durable results, lifecycle ownership, bots, channels, and delegation.

Develop Lightspeed

The development guides take a repository change from the local edit loop through validation, contract generation, and release construction:

• Local development: choose launcher profiles, find the owning code, edit and restart processes, and preview docs.
• Testing and evaluation: choose focused tests, establish replay behavior, run live suites, and evaluate models.
• Changing contracts: update API and workflow consumers, preserve compatibility, and author database migrations.
• Contributing and releasing: prepare a contribution and understand CI, packaging, snapshots, and publication.