Documentation

Install

From a terminal (recommended)

macOS and Linux:

curl -fsSL https://lautaro005.github.io/opencue/install.sh | sh

Windows (PowerShell):

irm https://lautaro005.github.io/opencue/install.ps1 | iex

Then start it with opencue (or from Applications, the Start menu or your app menu). The scripts install the latest release for your user without admin rights:

If ~/.local/bin isn't on your PATH, the script prints the line to add. Uninstall on macOS/Linux with curl -fsSL https://lautaro005.github.io/opencue/install.sh | sh -s -- --uninstall (your data is kept); on Windows use Settings → Apps.

Installers

Or download one from GitHub Releases:

The apps aren't notarized or code-signed by Apple or Microsoft yet. On macOS, a downloaded .dmg is blocked the first time: open System Settings → Privacy & Security and choose Open Anyway (the terminal install doesn't need this). On Windows, SmartScreen may show More info → Run anyway. Updates are signed and checked by the app.

Your first agent

The first time you open OpenCue a floating walkthrough asks your name, connects a provider, picks a default model and creates your first agent. Replay it from Settings → General. To do it by hand:

1. Open Settings → Providers (Ctrl+,) and set one up — paste an API key, or pick Ollama / LM Studio if you run models locally. Settings → Models then lists its models, with a search bar and switches to hide the ones you never use.
2. Click + at the top of the sidebar → Create Agent. Give it a name, a face, a sentence about what it should help with, and the provider and model.
3. Say hi. Click the person icon at the top right to open its profile, or the screen icon to open its computer.

Closing the window keeps OpenCue in the tray so automations and running agents keep working. Quit from the tray icon.

Model providers

Every agent uses one provider and model, picked when you create it or later in its profile → Model. Settings → Providers shows a container for every supported provider; click one to connect it. Settings → Models lists the models of the providers that are ready — search them and switch off the ones that shouldn't appear in pickers; the star sets a provider's default model.

Why the CLI route? OpenAI and Anthropic don't offer sign-in for third-party apps with consumer subscriptions, and copying their tokens breaks their terms. Running the official CLI keeps your subscription inside the official client.

OpenCue tools for CLI agents

CLI agents get OpenCue's own tools — memory, web, skills, their computer, files, email and Composio — through MCP: OpenCue hands the CLI a server started as opencue mcp-serve --agent <id>. Turn it off per agent in profile → Model → OpenCue tools. The CLI can't show OpenCue's approval cards, so in Ask first mode actions that need approval (sending email, commands on your computer, deleting memories…) are refused and the agent tells you instead. Your own MCP servers configured in OpenCue aren't passed on; configure those in the CLI itself.

Profile & avatar

Click an agent's face in its profile to change it in a floating window: ten faces, twelve shapes and a color row. The profile is organized like this:

• Assets — Mails (its inbox), Computer (where it runs commands) and Files (everything shared in the chat).
• Configurations — Model, Apps, Skills, Instructions, Memory, Voice and Permissions.
• Automations — what wakes the agent up by itself.

Instructions & memory

Instructions are the agent's job description, added to every conversation. They are saved as agents/<id>/INSTRUCTIONS.md. The soul (agents/<id>/SOUL.md) says who the agent is: personality, tone and values. Every agent also gets a short built-in prompt that tells it it is an agent inside OpenCue; you never see or edit it.

A new agent opens the chat by asking what its job will be. It writes its own instructions and soul from what you tell it, and keeps them up to date as you talk (models without tools get the same result from a small pass after each reply). Edit either in the agent's profile, or turn Let the agent write its own profile off.

Memory is a list of facts the agent keeps about you and its work, in agents/<id>/MEMORY.md. Agents save facts with the remember tool, look them up with recall and delete with forget (which asks first). You can add, delete or edit the Markdown directly.

• Shared memory (memory/GLOBAL.md) is visible to every agent that has “Use shared memory” on.
• Learn from conversations automatically is on by default: after each reply the model decides whether anything is worth remembering, sends facts every agent should know to the shared memory, skips duplicates and merges the list when it passes 40 entries. Turn it off per agent in its Memory page.

About me (Settings → Account) is a description of yourself that every agent reads as background, together with your name. It stays on your computer and goes only to the model provider you chose.

Group chats

Create one with + → Create group chat. The first member is the owner.

• @Name makes that agent answer. Without a mention, the owner's model picks who should reply.
• Agents hand work to each other by mentioning them or with send_to_agent.
• Automatic turns (group details) caps how many hand-offs happen before the group waits for you.

Files

Attach files with + → Files in the message box, by dragging them onto the chat, or by pasting an image. Up to 10 files per message, 25 MB each.

• Each file is copied into the workspace of the agent (or of every member of a group) as files/<name>, so agents with a computer can open it with their tools.
• Pictures (PNG, JPEG, GIF, WebP) are sent to models that can see images; small text files (up to 40 KB) are included in the message.
• Agents with a computer send files back with share_file — a report, a spreadsheet, a chart — and they appear in the chat like yours.
• Click a file to open it; hover for Save as… and Show in folder. Every file shared in a chat is listed in the agent's Files page or the group's Files section.

Files are kept in the files/ folder of your data folder.

Approvals

In Ask first mode (the default) these wait for you to click Allow in the chat:

• Sending email
• Commands and file writes on This computer or WSL
• Deleting a memory
• MCP tools not marked read-only, and Composio actions that may change data

Fully autonomous runs everything without asking. Use it only with tools and content you trust.

Apps, MCP & Composio

MCP servers

Settings → Apps accepts local servers (a command such as npx -y @modelcontextprotocol/server-filesystem ~/Documents), remote servers by URL (Streamable HTTP), or an imported Claude Desktop–style mcp.json:

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/Documents"] },
    "remote": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer …" } }
  }
}

In an agent's Apps page choose all servers or only some.

Composio

Composio connects 500+ apps (Gmail, Slack, Notion, GitHub, Google Calendar…). OpenCue takes either kind of Composio key: a consumer key (ck_…, the one Composio Connect gives you for MCP clients; OpenCue talks to connect.composio.dev/mcp with it in x-consumer-api-key) or a project key (ak_…, Platform → Settings → API Keys, used with Composio's API in x-api-key). The key stays in your keychain.

1. Create a Composio account and paste your API key in Settings → Apps → Composio. The User ID is the Composio user whose connected accounts agents should use (default if empty).
2. Under Connect an app, touch the search field to see the apps (type to filter) and pick one. Sign in in the browser page that opens, then press Refresh. You can also connect apps in the Composio dashboard.
3. Turn on Composio apps in an agent's Apps page. With a project key it gets two tools: composio_search to find an action and composio_execute to run it. With a consumer key it gets Composio Connect's own tools (COMPOSIO_SEARCH_TOOLS, COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_MANAGE_CONNECTIONS…). There is no built-in shared key: each person uses their own Composio account.

Skills

Skills are folders with a SKILL.md file, the same format as Claude Code Agent Skills:

---
name: weekly-report
description: Write the Friday status report from this week's notes and emails.
---

1. Read the notes in the workspace from Monday to today.
2. Search the inbox for "status" from this week.
3. Write a short report with Done / Next / Blocked.

Agents see each skill's name and description and load the full instructions with use_skill when a task matches. Create and edit skills in Settings → Skills, import one from a URL (GitHub links work), or let an agent save one with save_skill after you teach it something. Skills live in the skills/ folder and are shared by all agents; turn them off per agent in its Skills page.

Slash commands

Type / in the chat input to list commands; arrows and Enter pick one. Every installed skill is a command (/weekly-report for this month loads it and follows it). Two are built in: /create-automation makes the agent create an automation for itself (a schedule or new-email trigger; it asks first in Ask-first mode) and /create-skill makes it write a reusable skill from what you described.

Email

Profile → Mails → Add. Two account types:

• IMAP / SMTP — any provider. Gmail, Outlook, Yahoo, iCloud and Fastmail servers fill in automatically. With 2-step verification use an app password. The password goes to your system keychain.
• Gmail via Composio — uses the Gmail account connected in Composio.

The agent gets read_emails, search_inbox (plain words, or from: / subject:) and send_email. Sending waits for approval in Ask-first mode. Email content is treated as data: agents are told not to follow instructions written inside messages.

Automations

In the profile's Automations section click +. Each automation has a trigger and a prompt; when it fires, the prompt appears in the agent's chat as an event and the agent gets to work.

curl -X POST http://127.0.0.1:7777/hooks/YOUR_TOKEN \
  -H 'Content-Type: application/json' \
  -d '{"event":"deploy finished","status":"ok"}'

The automation list describes schedules in plain words (“Weekdays at 9:00”), and so does the editor as you type a cron expression. The webhook server listens on 127.0.0.1 only. Change the port in Settings → Computers → Webhooks. Automations run while OpenCue is open or in the tray.

Computers

Profile → Computer picks where an agent runs run_command, read_file, write_file and list_files. The screen icon in the chat header opens the live terminal and a file browser; you can type your own commands there too.

Local VM: live desktop, resources and a folder that keeps its state

In an agent's profile → Computer → Local VM (Docker) you can turn on the live desktop (watch and use it in the Desktop tab), give the VM memory (1–16 GB) and CPUs, and choose the VM folder. That folder is the VM's home — desktop settings, browser profile, downloads and anything you install under it — so nothing is lost when you close OpenCue, the VM stops or it is recreated. By default it is a folder of its own inside OpenCue's data directory; pick any other folder to keep it where you want (an external disk, a synced folder…). Changing memory, CPUs, the desktop or the folder recreates the VM the next time it starts; the workspace and the VM folder are kept.

VMPal machines

VMPal virtual machines can be controlled by agents through MCP. Declare each machine in Settings → Computers → VMPal as TOML, the same way Codex declares MCP servers:

[mcp_servers.vmpal-work]
command = "/Applications/VMPal.app/Contents/Helpers/VMPalMachine.app/Contents/MacOS/VMPalMachine"
args = ["--mcp", "E7D-your-machine-id"]

In VMPal, turn on agent control for the machine (its Settings › AI Agents) and keep it running; if it is off, the agent starts it with its vmpal_start tool. Then open an agent's profile → Computer → VMPal and switch on the machines it may use — or press Add machine to paste a new table there, which adds it to the shared list and selects it. A machine starts the first time that agent replies; Test connection in Settings starts it now. VMPal machines are never part of “all MCP servers”, and in Ask-first mode their tools ask for approval unless they declare themselves read-only.

Setting up SPACE

1. On a Linux machine with /dev/kvm, run scripts/check-space-host.sh from the repository to check the basics.
2. Install SPACE following its documentation.
3. In Settings → Computers → SPACE, paste the API URL (for example http://host:8080/v1), the template to boot and the API token, then Test connection.

Each agent gets its own sandbox, created on first use and woken up when it was suspended.

Desktop view (Docker)

Turn on Settings → Computers → Docker → Desktop view and Docker computers start from an image with a desktop you can watch and use in the Desktop tab of the Computer panel (widen it with the arrows icon). Programs the agent starts with run_command appear there (DISPLAY=:1).

• Default image: linuxserver.io Webtop (lscr.io/linuxserver/webtop:ubuntu-xfce, web port 3000). Any image that serves a web desktop works — noVNC, KasmVNC or Selkies — set its image and port.
• The port is published on 127.0.0.1 only, on a random free port.
• Existing computers keep their old container: use Restart computer in the Desktop tab. Restarting keeps the workspace.

Voice

1. Create an ElevenLabs API key and paste it in Settings → Voice.
2. Press the microphone in the message box, speak, press it again. Your speech is transcribed (Scribe) and sent.
3. With Read replies aloud on, the agent's answer is spoken. Pick a default voice there, or a voice per agent in its Voice page.

Internet

Agents with web access get web_search (DuckDuckGo and Wikipedia, no API keys) and web_fetch (any page, converted to Markdown). Results are cached in the local database. If you host SearXNG, add its URL in Settings → Internet and it is queried first.

Working folder

In an agent's profile, Working folder shows where it runs commands and keeps files: by default a folder of its own inside OpenCue's data directory. Choose folder… (or type a full path) points it at a project or any folder you want it to work on; the folder is created if it doesn't exist, and Use the default goes back. Files you share and files it creates live there, and a Docker computer mounts it at /workspace. In Ask-first mode, commands and file writes on your computer still wait for your approval.

Notifications

Settings → Notifications turns on system notifications for finished replies and for actions waiting for your approval. By default they appear only when OpenCue isn't in front; you can show just “New message” instead of the text, and send a test. On macOS and Windows allow OpenCue in the system's notification settings if nothing appears. The icon in the menu bar (or tray) opens a menu with Open, Settings, Check for Updates and Quit.

Updates

OpenCue checks GitHub Releases for a new version a few seconds after it starts. When there is one, a note appears at the bottom of the sidebar; Settings → About → Install and restart downloads it, verifies its signature and restarts. Turn off the automatic check there. In-app updates work for the macOS app, the Windows installers and the Linux AppImage; .deb and .rpm installs update through a new download.

Data & privacy

Inside: opencue.db (agents, chats, settings, automations, web cache), agents/<id>/ (instructions, memory, workspace), files/ (files shared in chats), memory/GLOBAL.md and skills/. Set OPENCUE_HOME to use another folder. Secrets (API keys, email passwords, tokens) go to the system keychain, or a 0600 secrets.json if there is none. See the privacy policy for what leaves your computer.

Command line

opencue-cli (zipped with each release) uses the same data folder as the app:

opencue-cli providers add anthropic --key sk-ant-…
opencue-cli agents create "Nova" --instructions "Plan my trips"
opencue-cli chat Nova --message "Find a quiet hotel in Montevideo"
opencue-cli mcp import ~/.config/Claude/claude_desktop_config.json
opencue-cli search rust async traits
opencue-cli mcp-serve --agent <id>   # OpenCue's tools as an MCP server (stdio)
opencue-cli where

The desktop binary understands opencue mcp-serve --agent <id> and opencue --version too.

Build from source

Rust (stable), Node 22+, and on Linux libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev. On macOS, the Xcode command-line tools.

git clone https://github.com/Lautaro005/opencue
cd opencue/apps/desktop
npm install
npm run tauri dev     # the desktop app
npm run tauri build   # installers for your system

Release builds create signed update bundles, so tauri build needs TAURI_SIGNING_PRIVATE_KEY; for a local build without it, add -c '{"bundle":{"createUpdaterArtifacts":false}}'.

FAQ

Is it really free?

Yes. You pay only for the model API you choose, or nothing with local models. The license lets you use, change and share OpenCue but not sell it.

Does OpenCue have phone numbers or payments like Cue?

No, on purpose: no phone, wallet or payments.

Is it safe to let agents run commands?

Prefer Docker or SPACE: they are isolated from your files. On This computer, keep the agent in Ask-first mode and read each command before allowing it. Report security problems privately — see the security policy.

Something broke.

Open an issue on GitHub with your system, version (Settings → About) and steps to reproduce.