Docs
GitHubBlog

Search Documentation

Search for a page in the docs

macOS

The shortest path on macOS is the signed desktop build for your architecture:

The package bundles its own Node runtime, managed Pi agent, pinned fd and ripgrep search tools, and git path; supervises the optional UTA service plus Alice backend; opens the UI in a native window; and uses the same ~/.openalice data store as a source checkout.

Requirements

  • Apple Silicon or Intel Mac matching the downloaded package.
  • macOS with permission to run a signed downloaded app.
  • A model credential for at least one agent path:
    • easiest packaged path: use the included managed Pi runtime and add a compatible API-key credential in AI Providers, or
    • install Claude Code, Codex, opencode, or Pi yourself and use that CLI's normal login/configuration.

Install

  1. Download the .dmg.
  2. Open it and move OpenAlice into Applications.
  3. Launch OpenAlice.
  4. If macOS asks for confirmation, allow the signed app to open.
  5. Wait for the app window to load Ask Alice.

OpenAlice stores user data outside the app bundle, under ~/.openalice. Updating or replacing the app does not erase your workspaces, config, Inbox, sessions, or broker-account data.

Configure an agent

The desktop package already contains managed Pi, but it does not contain a model account or API key. For the no-terminal path, open Settings → AI Provider, save a compatible credential, and set it as Pi's default Workspace credential. New Pi workspaces receive that config automatically.

OpenAlice can also use native agent CLIs you installed yourself. If you use Claude Code:

claude

Complete the login flow once. New workspaces can then use that CLI subscription login.

The key is tested before saving and injected into future workspaces. Runtime availability and model credentials are separate: managed Pi supplies the runtime, while the AI Provider vault supplies the model connection.

When to use source instead

Use Source & Dev if:

  • the desktop app gets stuck before the UI loads;
  • you need terminal logs;
  • you want to patch or inspect the code;
  • you are testing broker or UTA behavior;
  • you are filing a bug and want reproducible output.

The desktop build is the shortest path, but source is still the better debugging path while OpenAlice is beta.

Next Steps