The CLI connects directly to the runtime. Platform can be added to the same runtime for accounts, team permissions and the web interface; neither CLI configuration nor API-key authentication requires it. The runtime still uses PostgreSQL, Temporal and its configured content storage.
From a source checkout, start either the runtime alone or the full product:
./dev.sh runtime --no-envdUse ./dev.sh --no-envd to include Platform. Both profiles default to
authenticated mode. After migrations, the launcher creates the initial
universe and provisions separate CLI and Platform keys as needed. The initial
universe receives the slug development if it has no slug; an existing slug
is preserved. Universe listings show (no slug) for unnamed universes. In another
terminal, from the same checkout:
cargo build --locked -p cli
target/debug/lightspeed connect dev
target/debug/lightspeed connect statusThe launcher writes a handoff under .lightspeed/cli/. Its key files are
owner-only and ignored by Git. connect dev verifies and selects a saved
connection specific to this checkout. It preserves that connection's universe
selection on subsequent imports. Starting the launcher alone does not change
your selected CLI connection.
Ordinary restarts reuse the keys. Adding Platform does not rotate the CLI key.
After a successful ./dev.sh reset, the launcher clears its saved credentials
and handoff. The next startup provisions development keys again; run
lightspeed connect dev afterward to refresh the CLI connection.
Revoked keys, missing saved secrets or keys absent after a manual database reset
require explicit repair; startup does not silently issue another administrator
key. To replace a key, provision a new one with the server command described
below, put its secret into the corresponding protected .lightspeed/cli/cli.key
or platform.key file, then restart and run connect dev again for the CLI.
If replacing an active key, revoke the old one explicitly too.
Use --no-api-key-bootstrap on either launcher profile to manage keys yourself.
It preserves authenticated mode and normal startup preparation, including
migrations and universe setup. Platform then needs an existing service key.
Without a CLI handoff, use connect add with your own credential.
For explicitly unauthenticated local development:
LIGHTSPEED_AUTH_MODE=single ./dev.sh runtime --no-envd
target/debug/lightspeed connect devSingle mode uses the server's configured universe and sends no identity headers. Authentication failures never cause an automatic switch to this mode.
On the server host, configure the runtime stores and secrets as described in Self-hosting, then run:
lightspeed-runtime migrate
lightspeed-runtime api-key provision --name "Initial operator"From source, replace lightspeed-runtime with
cargo run -p temporal-runtime --. The provision command prints JSON containing
the secret; capture it securely. It creates a deployment key with every method
group and no actor assertion. No universe is needed yet.
To supply a key from deployment secret configuration, set
LIGHTSPEED_BOOTSTRAP_API_KEY for the provision command. Its format is lsk_
followed by 32 random bytes encoded as unpadded base64url. The command stores
only its hash and metadata in the normal key store. Repeating it with the
same active key is idempotent; revoked keys and authority mismatches fail.
The runtime never authenticates directly against this environment variable,
and ordinary server startup does not provision keys.
Start the server in LIGHTSPEED_AUTH_MODE=authenticated. On the client:
lightspeed connect add production --url https://runtime.example/rpc
lightspeed connect use production
lightspeed universe create --slug personal
lightspeed universe use personalconnect add prompts for the key without echoing it. For headless use,
choose --api-key-file /protected/key, --api-key-env MY_RUNTIME_KEY, or
--api-key-stdin. Environment/stdin/prompt input is stored in a protected
local credential file; an explicitly supplied file remains externally owned.
Use --single only for a server explicitly configured for single mode.
lightspeed connect list
lightspeed connect status
lightspeed connect use production
lightspeed universe list
lightspeed universe use personal
lightspeed universe status
lightspeed universe set-slug personal my-personal
lightspeed --connection production --universe staging session list
lightspeed connect remove productionadd saves without selecting; use selects an existing connection. remove
forgets local configuration and owned local credential material without
revoking the runtime key or deleting external credential files. Removing the
active connection clears the selection.
The global --connection selects a saved endpoint and credential together,
ignoring ambient connection environment variables. Explicit --api-url on
commands that accept it can override the endpoint, but never forwards a saved
key to a different endpoint. Without --connection, LIGHTSPEED_API_URL,
LIGHTSPEED_API_KEY and LIGHTSPEED_UNIVERSE override saved settings.
--universe overrides universe selection for one invocation; it does not
change the saved default. The CLI loads a root .env when present, so check
for old overrides there if the effective connection is unexpected.
Saved connections live in $XDG_CONFIG_HOME/lightspeed or
$HOME/.config/lightspeed. LIGHTSPEED_CONFIG_DIR overrides that directory.
connect status groups the effective connection and key authority, followed by
the selected universe's current slug and UUID. universe status shows just the
active universe. Both resolve the effective selection, including environment
and command-line overrides or a universe bound by the server. Status reports
when no universe is selected, or when its slug cannot be read with the current
key. Slug lookup requires deployment authority and the deployment/universes
group (or single mode); a universe key still shows its bound UUID.
universe list marks the active universe with *; it marks none if there is no
selection. These commands support --json, as does connect list. JSON status
includes the slug and UUID; JSON universe lists include each row's active
flag and the effective activeUniverseId.
| Authority | Universe selection |
|---|---|
| Deployment key | Select by core UUID or slug. Listing/slugs require deployment/universes; explicit UUIDs work without listing permission. |
| Universe key | The key selects its universe. Conflicting overrides fail; no universe header is sent. |
| Single mode | The server selects its configured universe; no identity headers are sent. |
Runtime slugs are optional and unique within a deployment. universe set-slug
assigns or changes one without changing the UUID, resources, keys or saved CLI
selection. Renaming releases the old slug; old Platform URLs can stop working
or refer to another universe if that slug is reused.
Deployment operations omit the universe header even when a universe is selected. Keys remain constrained by their allowed groups. A direct runtime key's authority is independent of Platform membership and session visibility. See API keys and service access.
Provider credentials are separate from the Lightspeed gateway key. Store a built-in provider key from an environment variable:
lightspeed model provider add openai --api-key-env OPENAI_API_KEY
lightspeed model listFor a compatible endpoint, supply its full configuration:
lightspeed model provider add my-provider \
--base-url https://provider.example/v1 \
--api-kind openai:completions \
--api-key-env MY_PROVIDER_KEYRepeat --api-kind for multiple supported APIs and --header NAME=VALUE for
non-secret headers. For a credentialless endpoint, use --no-auth instead of
a key source. The runtime validates endpoint configuration; its loopback URLs
refer to the runtime host. Provider setup requires the auth group and model
discovery requires models.
Choose a discovered route explicitly when starting a new session:
lightspeed chat --provider my-provider --api-kind openai:completions --model MODEL_IDWithout those flags, a new session uses its profile's model, if supplied, then
the universe's agent-run default. Configure that default below or select a
route explicitly. Provider identity and API kind are fixed for each session;
/model can choose another compatible model within that route. Retained native
state can restrict that choice. The TUI footer shows the connection name and universe slug
for saved or explicit runtime connections; generated local-development
connections omit this label. The footer also shows the current session ID,
shortening UUIDs while preserving readable IDs. If the universe slug is
unavailable, the footer uses a short universe UUID. /status shows the full connection name, endpoint,
authentication scope, universe slug/UUID and current session ID. Connection
details are captured when chat opens, with no background polling. Each process
keeps its resolved connection; switching saved defaults elsewhere does not
retarget a running chat. See Sessions and runs for
history, session switching and run controls.
For a quick view of recent conversations:
lightspeed chat --list
lightspeed chat --list --json
lightspeed chat --resume
lightspeed chat --continue--list shows up to 10 unmanaged root sessions in the selected universe,
most recently updated first, with names, lifecycle status, current activity
and time since the last update. Managed sessions and delegated subagents are
excluded; closed sessions remain visible in the list. JSON output includes
the full summaries and timestamps.
--resume and its alias --continue open the most recently updated unmanaged
root session that is not closed, preserving its configuration and attachments.
If none exists, the command explains how to start a new chat. It never creates
a replacement for a session deleted between listing and opening it. Use
chat -s SESSION_ID to choose a specific session instead. Listing and resuming
use the effective connection and universe, including command-line overrides.
To give the session files, upload a local directory or attach an existing runtime workspace:
lightspeed chat --upload .
lightspeed chat --workspace WORKSPACE_ID --workspace-path /repo --workspace-access read
lightspeed chat -s SESSION_ID--upload takes a one-time snapshot and creates a new runtime workspace. Local
files are not kept in sync, and agent edits are not written back to your machine.
--workspace reuses an existing workspace. Choose one of these options; both
default to /workspace with edit access. --workspace-path and
--workspace-access read|edit require one of the two sources.
These shortcuts use the same revision-checked attachment operation as
session workspace attach. They replace an attachment at the specified path
and preserve other attachments and configuration. Repeating --upload creates
another workspace. Resuming with chat -s SESSION_ID alone retains the session's
existing attachments. Every --session option also accepts -s.
Model defaults belong to the selected universe, separately from provider credentials and the CLI's saved connection:
lightspeed model defaults read
lightspeed model defaults set agent-run --provider my-provider --api-kind openai:completions --model MODEL_ID
lightspeed model defaults set speech-to-text --provider openai --api-kind openai:audio-transcriptions --model TRANSCRIPTION_MODEL_ID
lightspeed model defaults clear speech-to-textUse a model supported by the configured provider. These commands require the
models method group. set and clear read the current revision before
writing; use --expected-revision REVISION to require a revision you already
read. All three commands support --json.
An explicit session model takes precedence over a profile model, followed by
the agent-run default. Without any of these, creation fails with
model_default_unset. Changing or clearing defaults leaves existing sessions
and admitted transcription jobs unchanged. A resumed chat uses its stored
model. See Models and credentials.
LIGHTSPEED_CHAT_PROVIDER and LIGHTSPEED_CHAT_MODEL are retired and prevent
runtime startup. Remove them from deployment configuration and save the
intended routes with these commands.
A deployment key with deployment/api-keys can issue narrower keys:
lightspeed api-key create --name "Agent client" --universe-id UNIVERSE_UUID \
--group session --group models --group vfs --group blobs/put
lightspeed api-key list
lightspeed api-key rotate KEY_PREFIX
lightspeed api-key revoke KEY_PREFIXRotation replaces the secret immediately and prints its replacement once. Use the returned prefix for later key-management commands and update every client using the old secret. Scope and permissions stay the same.
Create prints the secret once; use --json for machine-readable output. Add --group auth if the client needs
to configure provider credentials, and other groups for the resources it
manages. Omitting groups grants every group allowed by the chosen scope.
These are integration credentials, not personal Platform login tokens.
To add Platform, give it its own deployment service key with the required method groups and actor assertion. Use Platform's administrator adoption flow to link an existing runtime universe. Platform uses the runtime slug for its URLs and caches it for lookups. Creation sends the requested slug to runtime; adoption preserves an existing slug or requires one to be assigned to an unnamed universe before linking. Platform does not invent a different slug on collision. Ordinary universe lists and reads use Platform's database without contacting runtime. Creation, adoption and renaming through Platform's general settings immediately cache the slug returned by runtime. After a CLI or direct API rename, a Platform administrator must use Sync from runtime on the Universes page to update the cached URLs. There is no periodic or background slug refresh. A failed sync reports an error and preserves the cache; missing or unnamed runtime universes are reported as skipped for review. During runtime outages, the cached universe list remains available for membership administration. Linked universes across different runtime deployments must have distinct slugs within one Platform.
IDs, profiles and sessions stay in the runtime; Platform creates only its organization and membership records. This association does not automatically share private sessions. Direct CLI access continues to work while Platform is stopped.
Resource commands use singular names and accept plural aliases: universe(s),
api-key(s), session(s), profile(s), model(s), workspace(s), credential(s),
environment(s), and mcp/mcps. env is also an alias for environment.
connect (connections) manages local connection settings; chat (chats)
starts or continues a conversation. vfs (vfses) uploads and downloads
immutable snapshots. --connection, --universe, and --api-url can appear
before or after subcommands. The endpoint override follows the same credential
isolation rules as saved connections.
Workspaces, MCP registrations, credentials and environments belong to the selected universe and have independent lifecycles. Session attachments declare which resources an agent may use. Changing an attachment preserves unrelated configuration and checks its revision; configuration changes require an idle session. Attaching an environment does not activate or provision it.
lightspeed workspace list
lightspeed workspace create --display-name project
lightspeed mcp list
lightspeed mcp tools my-server
lightspeed mcp login my-server
lightspeed credential list
lightspeed credential import --provider-id my-service --token-env SERVICE_TOKEN
lightspeed model provider list
lightspeed environment list
lightspeed profile list
lightspeed session read SESSION_ID
lightspeed session config read SESSION_ID --json > session-config.json
lightspeed session config put SESSION_ID --file session-config.json
lightspeed session profile apply SESSION_ID --profile reviewer
lightspeed session workspace attach --session SESSION_ID --workspace WORKSPACE_ID --path /repo --access read
lightspeed session mcp attach SERVER_ID --session SESSION_ID --tools search,fetch
lightspeed session environment attach ENVIRONMENT_ID --session SESSION_ID --access exec --working-directory /repo
lightspeed session environment activate ENVIRONMENT_ID --session SESSION_ID
lightspeed session skill list --session SESSION_ID
lightspeed session skill use SKILL_ID --session SESSION_IDThe workspace, MCP and environment groups under session each provide
attach, detach and list. Lists show declared attachments rather than
inferring them from materialized tools. Detaching does not delete the resource.
Environment lists mark the active attachment. Skill selection submits ordinary
agent input (or steers an existing run); there is no separate skill execution
or installation registry.
credential manages external credentials, not authentication to Lightspeed.
Its oauth-client and github subcommands configure reusable OAuth clients and
GitHub Apps. Model endpoint credentials belong under model provider; MCP
credential binding and OAuth login belong under mcp. api-key manages keys
that authenticate callers to Lightspeed itself. Runtime API method-group names
such as auth and models are unchanged.
Human output uses labeled details, table headers and explicit empty states.
Resource operations accept --json for scripts. OAuth authorization instructions
are written to stderr so JSON stdout remains parseable. Profile export always
emits a reusable JSON document; profile list/read/import/check use human output
unless --json is requested. Configuration put replaces a complete document;
omitted fields return to their defaults, except an omitted model preserves the
existing session model. It checks the revision read immediately
before the write, or the explicit --expected-revision supplied by the caller.
If a provider repeatedly rejects a particular user message or tool result, inspect the active context after the run has stopped:
lightspeed session context list SESSION_ID
lightspeed session context list SESSION_ID --jsonThe list follows model order and includes entry IDs such as item_12, kinds,
media handles when present, and bounded previews. Use the IDs actually
returned for that session. Replace an entry with useful text, or redact it
with a standard removed-by-operator placeholder:
lightspeed session context replace SESSION_ID item_12 "The command failed; its oversized diagnostic output was removed."
lightspeed session context redact SESSION_ID item_15 item_16Only active user messages and tool results can be replaced. A tool result keeps its call identity and position, so the provider still sees the call answered. Assistant messages, tool calls, and provider-native state cannot be edited this way. Replacement is refused while a run is active.
Inspect each reported result: replaced, unchanged, absent, or failed.
An entry that has already left active context is absent; a batch can report
different outcomes for different entries. List the context again before
continuing the conversation. These commands also support --json; API
clients use session/context/replace.
Redaction changes what future requests receive. Original events and blobs remain in retained history, so this is not a data-erasure operation. For a full context window rather than a specific rejected entry, use the compaction controls.
A deployment administrator registers a provider controller and binds it to a
universe. environment provider put takes the provider ID, its
--controller-endpoint, and optionally --display-name, --data-route-base
(required for a unix:// controller), and --credential-file; omitting the
credential keeps the stored one, and --clear-credential removes it.
environment binding put PROVIDER_ID --enabled (or --disabled) binds the
selected universe. These operations require a deployment key; provider
list/read/delete and binding delete do as well. Normal environment and
template operations operate within the selected universe.
lightspeed environment provider put incus-local --controller-endpoint ws://127.0.0.1:19090/control --credential-file ./provider-credential
lightspeed environment binding put incus-local --enabled
lightspeed environment template list --provider incus-local
lightspeed environment create --provider incus-local --template linux-v1 --request-id provision-my-machine
lightspeed environment register wss://machine.example/envd --request-id register-my-machine
lightspeed environment list --include-closed --limit 50
lightspeed environment read ENVIRONMENT_ID
lightspeed environment update ENVIRONMENT_ID --name "Build machine" --metadata team=release
lightspeed environment power ENVIRONMENT_ID paused
lightspeed environment ingress ENVIRONMENT_ID --enableReuse the same request ID when retrying an uncertain provisioning or external
registration request. Creation and closure of a provisioned environment are
asynchronous: inspect the returned state with environment read. power and
ingress wait for the provider's answer and print what it reported; the
provider keeps owning power afterwards. environment list omits closed
environments unless --include-closed is given, and returns one page at a
time; when more remain, it prints the --after value for the next page. environment update
replaces the display name and metadata, so omitted flags clear them.
Outbound daemons use environment registration-key create|list|read|update|rotate|revoke.
update replaces a key's group name and policy, including
--offline-close-after-min for a persistent key; rotate prints a new secret
once and retires the old one. Credentials bound with environment credential bind supply the environment's configured secret references; attachment
access controls the agent's permitted use of the machine.