Skip to content

Quickstart

Install Lucidos on a clean macOS or Linux machine, then connect it to an LLM provider.

On macOS, the fastest route is the signed, notarized desktop app. Download 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. This page covers both.

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? The front door serves the uninstaller beside the installer. Pass the same flags after sh -s --:

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

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

Run Lucidos from a source checkout and it can work on its own code. It proposes each change as a diff that you review and Apply. See Develop Lucidos for that loop, its dev setup, and how to contribute.

Next steps