Getting Started

This page walks you through your first 10 minutes with OpenLoomi — picking the install path that matches how you work, installing the binary, configuring an AI provider, and confirming a successful first run.

Goal

By the end of this page you should have:

1. OpenLoomi running on your machine (or wired into your existing agent shell).
2. An AI provider configured so OpenLoomi can answer prompts.
3. A clear "first success" — a connector, a memory write, or a Loop tick — depending on your path.

Choose a path

Before you begin

• macOS 13+, Windows 10 (64-bit), or Ubuntu/Debian 20.04+ on x86_64 / ARM64.
• 4 GB of RAM and ~500 MB of free disk space.
• An internet connection for sync and messaging features.
• An API key or local CLI auth for at least one supported AI provider — see AI Configuration.

System Requirements

Download

macOS

# If you have a manual installation, remove it first:
# rm -rf /Applications/openloomi.app

# Install via Homebrew
brew tap melandlabs/openloomi https://github.com/melandlabs/openloomi
brew install --cask openloomi

# Upgrade
brew upgrade --cask openloomi

# If install or upgrade fails with "App source is not there", clear cache and reinstall:
# rm -rf ~/Library/Caches/Homebrew/openloomi
# brew uninstall --cask openloomi
# brew install --cask openloomi

Linux (Ubuntu/Debian)

sudo dpkg -i openloomi_0.8.8_linux_amd64.deb
sudo apt-get install -f

# Fix resource path (required for v0.8.8 and earlier)
sudo ln -sf /usr/lib/openloomi/_up_ /usr/bin/_up_

# Start the application
openloomi

Linux (Fedora/RHEL)

sudo dnf install ./openloomi_<version>_x86_64.rpm
# For ARM64 systems, use openloomi_<version>_aarch64.rpm

# Start the application
openloomi

Windows

View all releases →

Use as a Plugin (For Claude Code / Codex Users)

Don't want to install the desktop app? OpenLoomi also ships as official marketplace plugins that turn your existing agent (Claude Code or Codex CLI) into a front-end for the local OpenLoomi runtime.

For full documentation, see the plugin docs:

• Claude Code Plugin
• Codex Plugin

Use as a Skills.sh Skill Pack

For agent runtimes that only consume the skills.sh skill protocol, install the OpenLoomi skill set directly from this repository:

npx skills add https://github.com/melandlabs/openloomi/tree/main/skills \
  --skill openloomi openloomi-setup openloomi-memory openloomi-connectors openloomi-loop openloomi-goals openloomi-api openloomi-feature-guide composio \
  -y

Start with the openloomi or openloomi-setup skill. The first setup pass checks whether OpenLoomi Desktop is installed, whether the local API is reachable, and whether a local session token is available. If OpenLoomi Desktop is missing, the skill points you to the official Downloads section above before continuing.

Permissions

When you first launch OpenLoomi, the system will ask for a few permissions. Each one has a specific purpose — and you can decline any of them. OpenLoomi will continue to work; you'll just lose the feature that requires that permission.

macOS

How to grant or revoke:

1. Open System Settings → Privacy & Security
2. Find the permission category (e.g., Full Disk Access, Automation, Notifications)
3. Toggle OpenLoomi on or off

You can revisit these settings at any time.

Windows

Windows SmartScreen may also show a one-time warning when running the installer. Click "More info" then "Run anyway" — this is normal for open-source software. You only need to do this once per machine.

Linux

No special permissions are required on Linux. OpenLoomi uses the standard desktop notification system (libnotify) to send alerts if you have granted notification permissions to other apps, OpenLoomi will automatically use them too.

AI Configuration

When you start OpenLoomi for the first time, the desktop app walks you through picking an AI runtime and completing the conversation API setup.

The onboarding screen — pick your AI agent and complete sign-in in a few clicks.

The API Settings panel — enter your provider's base URL, credential, and model name. OpenLoomi passes that per-user configuration to the selected runtime.

For the desktop app, complete runtime and model setup in Settings → Agent runtime and Settings → Conversation models. You do not need to edit Claude configuration files manually.

Default: Claude

OpenLoomi Desktop includes the Claude Agent SDK runtime, so users do not install a separate Claude CLI. Authenticate it with a complete Anthropic-compatible configuration saved in OpenLoomi, or reuse supported Claude authentication already available to the same OS account. For server deployments and shared installations, prefer an API configuration over a personal Claude login.

Supported Agents

In the desktop app, open Settings → Agent runtime to choose Claude, Codex, OpenCode, Hermes, or OpenClaw. Claude uses the runtime bundled with OpenLoomi; the others require their local CLI. Hermes can reuse the current user's saved Anthropic-compatible OpenLoomi API setting, while the remaining CLIs use their runtime-specific authentication or setup. OpenLoomi performs bounded, read-only readiness checks before enabling a switch; it does not start a model request. The saved device preference applies to new tasks and takes precedence over OPENLOOMI_AGENT_PROVIDER; running tasks are not interrupted. Use Use environment/default to remove that override.

Server/headless deployments remain environment-controlled. Claude is used when neither a desktop preference nor OPENLOOMI_AGENT_PROVIDER is set; supported environment values are claude, codex, opencode, hermes, and openclaw.

# OpenCode
OPENLOOMI_AGENT_PROVIDER=opencode
OPENLOOMI_AGENT_OPENCODE_COMMAND=opencode
OPENLOOMI_AGENT_OPENCODE_MODEL=anthropic/claude-sonnet-4.6

# Hermes
OPENLOOMI_AGENT_PROVIDER=hermes
OPENLOOMI_AGENT_HERMES_COMMAND=hermes
OPENLOOMI_AGENT_HERMES_PROFILE=coding

# OpenClaw (configure and start its Gateway first)
OPENLOOMI_AGENT_PROVIDER=openclaw
OPENLOOMI_AGENT_OPENCLAW_COMMAND=openclaw
OPENLOOMI_AGENT_OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789
OPENLOOMI_AGENT_OPENCLAW_TOKEN_FILE=/path/to/gateway.token

# Codex
OPENLOOMI_AGENT_PROVIDER=codex
OPENLOOMI_AGENT_CODEX_COMMAND=codex
# On macOS, run/execute maps workspace-write to danger-full-access.
OPENLOOMI_AGENT_CODEX_SANDBOX=workspace-write

For Codex, OpenLoomi links to the official installer and shows the login command, but does not run either one automatically. Claude is already bundled with the desktop app. External CLI runtimes receive a restricted environment; use OPENLOOMI_AGENT_ENV_ALLOWLIST only when one needs an additional named variable. Executable paths, runtime models, profiles, Gateway targets, and approval policy cannot be overridden by chat/API request bodies.

Agent runtimes and sandboxes are separate layers: OpenCode, Hermes, OpenClaw, and Codex are registered through AgentPlugin and do not pretend to be sandbox providers. Filesystem or process isolation must still be selected and enforced independently by the host.

See the Agent Runtimes reference for detailed runtime setup and security behavior.

Configure Claude in the desktop app

In Settings → Conversation models, save the API key or gateway token, base URL, and model under Anthropic compatible. Return to Agent runtime, select Re-detect, and choose Claude when its status is Ready. Use Test connection as an endpoint check, then start a new task to confirm the complete Agent SDK path.

Verify

After the desktop app starts and your AI provider is configured:

1. The desktop window opens and shows your Loop dashboard.
2. The pet widget on the desktop reflects the thinking → working → happy cycle.
3. Open the chat and ask "what did I work on yesterday?" — OpenLoomi should answer from your local Memory instead of returning an empty response.

If you're on the plugin path, confirm the readiness table lands on READY and /openloomi:status returns { "ready": true }.

Troubleshooting

• App doesn't open on macOS — confirm the binary is in /Applications (not quarantined in ~/Downloads). Re-run brew install --cask openloomi to repair.
• API key rejected — verify the credential, base URL, and model in Settings → Conversation models, run Test connection, then retry the task.
• Loop is silent — make sure at least one connector is enabled; otherwise there's nothing to surface.
• Plugin says OPENLOOMI_NOT_INSTALLED — re-run /openloomi:setup or @OpenLoomi Run first-use setup. to mint a guest session.

Next steps

• Connectors — wire up Gmail, Calendar, Slack, GitHub, Linear, and 1000+ apps via Composio.
• Memory — see how OpenLoomi's tiered storage and forgetting engine work.
• Loop — understand the decision cards Loop will start surfacing.
• Plugins — if you started from the desktop, try driving OpenLoomi from Claude Code or Codex CLI.