Installation Overview
Pick the path that matches what you are trying to do.
| I want to... | Start here | Notes |
|---|---|---|
| Run OpenAlice locally with the best-supported path | Source & Dev | Recommended today: visible logs, explicit updates, and the clearest recovery path. |
| Evaluate the desktop beta on Apple Silicon or Intel | macOS | Signed architecture-specific packages; packaging and updates are still beta. |
| Evaluate OpenAlice on Windows | Windows | The desktop installer is unsigned beta; source remains the best-supported path. |
| Evaluate the install script and headless Runtime | CLI & Remote Access | Beta convenience path while installer rough edges are being fixed; prefer source for daily local use. |
| Keep Alice in a container on a server | Docker | Image, healthcheck, bundled Agent CLIs, and persistent volume. |
| Keep the browser local while Alice runs on an existing private host | CLI & Remote Access | Installed headless Runtime, Server lifecycle, and SSH loopback tunnel. |
OpenAlice does not need a database. State is file-backed: config, sessions, trading history, news, issues, inbox entries, workspace artifacts, and provider settings live under ~/.openalice by default. Docker uses a persistent volume for the same role. See Data & Credentials when you need the exact layout, admin token recovery, sealed broker credentials, or port configuration.
Recommended path
For daily dogfooding today, start from source:
- Local user: clone the repository and run
pnpm install, thenpnpm dev. This is the current recommended path. - Mac user who wants the shortest no-terminal trial: use the signed
.dmgfor Apple Silicon or Intel if you accept desktop beta packaging; it includes managed Pi, so add an optional AI credential and start a Workspace without installing a separate agent CLI. - Windows user: prefer source for the clearest logs and debugging path; use the self-contained
.exeonly if you are explicitly evaluating the unsigned desktop beta. - Terminal-first local user evaluating the installer: the CLI can run bare
openalicewith its bundled headless Runtime, but this bootstrap path is still beta. Prefer source until the installer is hardened. - Existing private remote host: use the stable CLI and
openalice remote; no manual checkout path is required, and the read-only plan names every bootstrap action before consent. - Container operator: use Docker Compose, then put access behind LAN, Tailscale, or a reverse proxy. Docker and managed SSH are parallel first-class server paths with different ownership models.
The packaged desktop builds include their own Workspace runtime: Electron's
Node, managed Pi, and pinned fd/ripgrep, with PortableGit and Bash added on Windows. They still
need model access: let managed Pi manage access through its own login/provider
flow, configure an API key in Settings → AI Provider, or use another
installed Agent with its own login and configuration. If something
breaks and you want visibility, the source path is the easiest way to see logs,
patch locally, and report a useful bug. Treat desktop packaging and desktop
updates as beta until the release path has more miles on it.
OpenAlice 0.89.4-beta recognizes Cursor Agent (cursor-agent), Antigravity
(agy), Grok Build (grok), and Oh My Pi (omp) when those upstream CLIs are
on PATH. They use the same durable interactive/headless Session boundary but
are not bundled into the desktop packages; the runtime picker shows an install
hint when one is missing. See AI Providers
for authentication and model semantics.
Check the installed version
Open Settings → General → About OpenAlice to see the running version, runtime profile, release channel, and update status. Check for updates refreshes the release lookup immediately.
Desktop auto-update is still beta. If you are doing daily work and need the most debuggable path, use source or CLI instead of relying on in-app updates. The desktop UI reports determinate download progress, then Preparing the update, Safely stopping OpenAlice services, Finishing the current session, and Handing the update to the system installer without inventing an installer percentage. OpenAlice closes while the native installer replaces it and should reopen automatically; the handoff can take up to a minute.
Before closing, the desktop records a machine-local
openalice-update-attempt.json marker outside OPENALICE_HOME. The new version
clears it on first launch. If the old version is still present after the
installer window, OpenAlice archives the marker as .failed and reports the
failed target version and diagnostic log path instead of treating the handoff
as a silent crash. An Alice backend failure before the window loads likewise
shows the last diagnostic lines and log path in a native error.
Desktop diagnostics can contain local paths and Runtime context; review the bounded log before sharing it.
Release candidates now run an isolated previous-release-to-candidate desktop journey on Apple Silicon, Intel macOS, and Windows, preserving Workspace identity, display metadata, and renderer state before publication. This is a stronger upgrade gate, but packaged updates remain beta. If a package still cannot start, install the latest package again or switch to source; user data remains outside the app bundle under the selected OpenAlice home.
First thing after install
Once OpenAlice opens, do the core loop before connecting broker accounts:
- Open Quick Start.
- Ask Alice for a research task.
- Track an entity.
- Create or schedule an issue.
- Read the result in Inbox.
Broker execution is optional beta infrastructure. Use simulator, paper, demo, or testnet accounts first; read What is UTA before connecting live funds.
Next Steps
- macOS - Evaluate the signed desktop beta.
- Windows - Choose source or evaluate the unsigned desktop beta.
- Source & Dev - Clone, run, debug, test, and build.
- Docker - Run a long-lived server instance.
- CLI & Remote Access - Supervise local AliceProjects or connect to a private SSH host.
- AliceProjects - Separate complete homes, runtimes, and TraderAlice/NanoAlice product identity.