Skip to content

Quickstart

Get Lucidos running on a clean macOS or Linux machine, then point it at an LLM provider.

On macOS the fastest route is the signed, notarized desktop app: grab the .dmg from the latest release and drag it to Applications. The one-line installer below is the headless path (browser UI plus an always-on service), and the only path on Linux. Both are covered in full below.

Install

Two ways in, both first-class.

macOS: the desktop app. Download the latest Lucidos_<version>_aarch64.dmg from the releases page, open it, and drag Lucidos to Applications. It is signed and notarized by Apple (no Gatekeeper warning, no xattr dance), bundles PostgreSQL 18 + pgvector, the engine, and the UI, and auto-updates from GitHub Releases. Nothing else to install: no terminal, no Docker, no Rust or Node. Apple Silicon only today.

macOS or Linux: the one-liner. On a clean machine:

curl -fsSL https://lucidos.dev/install.sh | sh

This is the headless path: the same engine and UI served in your browser, plus an always-on background service. It is also the only path on Linux.

By default the installer DOWNLOADS the prebuilt headless runtime for your platform (the engine, the gateway, the frontend, and a relocatable PostgreSQL 18 + pgvector, all bundled), verifies its sha256 checksum, extracts it under ~/.lucidos/runtime/, and registers the bundled gateway as an always-on user service (a launchd LaunchAgent on macOS, a systemd --user unit on Linux) so it survives terminal-close + reboot and restarts on failure. The gateway provisions the embedded Postgres and supervises the engine, the same model as the macOS .app. No Docker, no Rust/Node, no clone, no compile. First run is seconds, not minutes. It opens at http://localhost:5252. Pass --no-service to run it in the foreground instead (Ctrl-C to stop).

One more way to get the headless runtime:

  • Install a tarball you built yourself with scripts/build-headless.sh: 
    ./install.sh --from-tarball /path/to/lucidos-<version>-<triple>.tar.gz
    It verifies the adjacent .sha256 (fail-closed on mismatch), extracts, and launches, fully offline.

Running from source is not a third way to install Lucidos: it is how you work on Lucidos. Neither shipped runtime carries the platform's own source, so neither can change it; a source checkout can, and that is the point of this path. Lucidos then works on its own code, proposing each change as a diff in an isolated git worktree for you to review and Apply. The whole loop, prerequisites included, is documented under Develop Lucidos. The one-command bootstrap for it is:

curl -fsSL https://lucidos.dev/install.sh | sh -s -- --dev

--dev (alias --source, or LUCIDOS_FROM_SOURCE=1) bootstraps the toolchain (Rust, Node, Docker, build deps), clones the repo to ~/lucidos, compiles the engine from source (a release build, typically 10–20+ minutes on a clean machine; LUCIDOS_DEBUG_BUILD=1 for a faster debug build), and starts the stack via scripts/run.sh.

On a brand-new release, the per-platform tarballs are attached by CI about 30 minutes after the GitHub Release is published, so a download started in that window can still 404. Retry shortly, pass --version <previous-version>, or use one of the two paths above.

The installer is idempotent, safe to re-run. The download/tarball paths skip an already-extracted runtime for the same version unless you pass --force; --dev reuses an existing checkout, build, and workspace.

Linux prerequisites. The prebuilt Linux tarballs are built against the Ubuntu 22.04 baseline, so they run on glibc 2.35+ distros (Ubuntu 22.04+, Debian 12+, Fedora 36+, RHEL/Rocky/Alma 10+). RHEL 9 and its rebuilds are below the floor: EL9 pins glibc 2.34 for its whole lifecycle. The installer runs the extracted gateway once and refuses any too-old host at install time with a clear message; build from source there instead (--dev). Two host packages are expected at runtime and warned about when missing: git (coding-agent threads + repository features) and ca-certificates (outbound TLS: LLM providers, the embedding-model download, web push). python3 is optional (script tooling).

Remote access & push notifications. The gateway listens on localhost only by default (the secure posture) and serves plain HTTP. Browsers grant service workers (and with them push notifications + PWA install) only on a secure origin (https or localhost), so to use Lucidos from other devices:

  • ssh -L 5252:localhost:5252 <host>, then open http://localhost:5252: the full app including push, zero config (localhost is a secure context).
  • tailscale serve --bg 5252: trusted HTTPS on your tailnet.
  • Or expose it directly: ./install.sh --bind all --tls-cert <cert.pem> --tls-key <key.pem>. --bind writes the machine-global ~/.lucidos/network.toml (the same knob as the picker's Settings → Network access); the TLS pair makes the gateway serve https (push needs a certificate your browsers trust). A bare --bind all without TLS serves the app over http://<host>, usable, but browsers will not grant push/PWA there.

Always-on service & multiple gateways. The default install registers a user-level service named after the instance. On macOS a launchd LaunchAgent com.lucidos.gateway.<name> at ~/Library/LaunchAgents/, on Linux a systemd --user unit lucidos-gateway-<name>.service at ~/.config/systemd/user/ (RunAtLoad/KeepAlive ≈ Restart=always; logs at <prefix>/<name>/logs/ on macOS, or journalctl --user -u lucidos-gateway-<name> on Linux). On Linux it also runs loginctl enable-linger (best-effort, may prompt for sudo) so the service survives logout/reboot. No supported service manager (e.g. a container without a user systemd session) → it degrades to a foreground launch with a clear message. You can run several gateways side by side as named instances that share the one downloaded runtime but each get their own data dir (<prefix>/<name>/), service, and port:

./install.sh                         # the 'default' instance (auto-picks a free port if 5252 is taken)
./install.sh --name test --port 5300 # a second, independent gateway
./install.sh --name test --port 5400 # move 'test' to a new port (the port is a mutable property)

The instance name is the stable identity; the port is a property you can change on a re-run. This is how a terminal install coexists with a dev gateway and the packaged .app.

Manage / uninstall. List instances, then stop + remove one (or all). Data is kept unless you pass --purge:

./install.sh --list                   # or: ./uninstall.sh --list
./uninstall.sh --name test            # stop + unregister 'test'; KEEP its data
./uninstall.sh --name test --purge    # also delete its data dir
./uninstall.sh --all --purge          # remove every instance + the shared runtime

./install.sh --uninstall [--name <name>] [--all] [--purge] is the same thing (it delegates to uninstall.sh).

--purge is irreversible and asks for no confirmation. An instance's data dir (<prefix>/<name>/) is not installer scratch: it holds the embedded PostgreSQL cluster (every thread, message, memory and setting of every workspace that gateway serves) and, for any workspace you created through the picker without choosing a path of your own, the workspace directory itself (<prefix>/<name>/workspaces/<id>/, i.e. your artifacts, apps, triggers and knowhow). --all --purge does that for every instance and deletes the shared runtime too. Back up anything you want to keep before adding the flag. Note that a bare uninstall is not a dry run either: it stops the gateway and removes its service, and only your data survives (it prints where it left it). The one command that changes nothing is --list, so start there.

Installed via the one-liner, so you have no checkout? Both are the repo's own scripts and the runtime lays no copy down (nothing under ~/.lucidos/ is an uninstaller), so download uninstall.sh and run it with the same flags:

curl -fsSL https://raw.githubusercontent.com/lucidos-dev/lucidos/main/uninstall.sh -o uninstall.sh
sh uninstall.sh --list

The matching https://lucidos.dev/uninstall.sh front door is not served yet, so piping that URL would feed you the landing page instead of a script. Tracked in docs/temporary-measures.md.

Pick your LLM provider (optional). With no credentials the runtime boots into a clear no-provider onboarding state (--dev boots in mock mode); configure a real provider in Settings → Providers afterwards. To wire one up at install time, pass it through the pipe:

# OpenAI (GPT models)
curl -fsSL https://lucidos.dev/install.sh | OPENAI_API_KEY=sk-… sh

# Vertex AI (Claude / Gemini), also run `gcloud auth application-default login`
curl -fsSL https://lucidos.dev/install.sh | VERTEX_PROJECT_ID=my-gcp-project sh

Knobs (all optional; flags or environment variables, see install.sh --help):
--name / LUCIDOS_INSTANCE instance name (default default); its data lives at <prefix>/<name>/
--version / LUCIDOS_VERSION version to download (default: the repo RELEASE when run from a checkout, else a baked default)
--base-url / LUCIDOS_RELEASE_BASE_URL where lucidos-<version>-<triple>.tar.gz + .sha256 live (default: the GitHub Releases path for v<version>)
--prefix / LUCIDOS_PREFIX install prefix (default ~/.lucidos); the shared runtime extracts to <prefix>/runtime/lucidos-<version>-<triple>/
--port / LUCIDOS_PORT the instance's gateway port (default 5252; a new instance auto-picks a free port if it's taken). Pinning it sets/changes that instance's port
--no-service / LUCIDOS_NO_SERVICE=1 run in the foreground instead of registering a service
--force / LUCIDOS_FORCE=1 re-download / re-extract the runtime even if already installed
--no-launch / LUCIDOS_NO_LAUNCH=1 install without starting the gateway
--uninstall / --list / --all / --purge manage instances (see above); --purge also deletes data
LUCIDOS_GATEWAY_DATA override the instance data dir (registry + embedded Postgres; default <prefix>/<name>)
--dev-only LUCIDOS_HOME (clone dir, default ~/lucidos), LUCIDOS_WORKSPACE, LUCIDOS_REF, LUCIDOS_DEBUG_BUILD, LUCIDOS_SKIP_DEPS

Prefer to drive the setup yourself? The manual path is below.

Working on Lucidos itself

Everything above is about running Lucidos. Running it from a source checkout is a different activity, and the reason to do it is not that you get a runtime out of it: it is that Lucidos can then work on its own code, proposing each change as a diff you review and Apply. See Develop Lucidos for that loop, the dev setup it needs, and how to contribute.

Next steps