OpenCore

OpenCore is a macOS AI operator with a local CLI and dashboard. It can reason about work, use local tools, edit files, coordinate sub-agents, and, when needed, use a computer-use executor to operate the Mac UI.

OpenCore now supports a hosted account layer:

• website-based sign in and onboarding-token generation during onboarding
• a backend-linked device session for each Mac
• centralized token-usage tracking from real model responses

Local runtime state still stays on the Mac for execution continuity. Credentials, screenshots, and agent markdown files remain local-only in the current production release.

Requirements

• macOS
• Node.js and npm
• Terminal access
• a reachable OpenCore backend
• a browser for hosted sign in
• an OpenAI API key

Recommended:

• a modern Apple Silicon Mac
• a browser for the dashboard
• Accessibility and Screen Recording permissions if you want computer-use

Backend Requirements

OpenCore onboarding now depends on a hosted backend and hosted auth UI.

Hosted stack:

• Prisma
• Neon Postgres
• a website auth layer that uses Clerk

Required environment for the local OpenCore install:

• OPENCORE_BACKEND_URL
• OPENCORE_WEBSITE_URL optional, defaults to http://localhost:3001 in local development

Required environment for the backend service:

• DATABASE_URL
• OPENCORE_PUBLIC_BASE_URL
• OPENCORE_WEBSITE_API_KEY

The website project, not the CLI/backend runtime, owns the Clerk keys.

Install

Install OpenCore globally:

npm i -g @opencoreai/opencore

Run onboarding:

opencore onboard

Start OpenCore:

opencore engage

Useful npm shortcuts in a repo checkout:

npm run onboard
npm run engage
npm run login
npm run logout
npm run whoami
npm run auth:status

Dashboard:

http://127.0.0.1:4111/dashboard/

First-Time Setup

opencore onboard is the production first-run flow.

Onboarding now starts with hosted account authentication before any local terminal questions.

Onboarding configures:

• your OpenCore account sign-in
• a persistent device session for this Mac
• your OpenAI API key
• the manager agent provider and model
• any extra manager-provider API key required for non-OpenAI manager models
• your name
• the tone OpenCore should use with you
• optional Telegram connection
• optional skill installation

If onboarding is incomplete, opencore engage will start onboarding automatically.

Important:

• OpenCore still requires an OpenAI API key in the current production release because computer-use execution remains OpenAI-backed.
• If you choose a non-OpenAI manager model, OpenCore will also ask for that provider’s API key.
• opencore onboard opens the hosted OpenCore website in your browser.
• by default in local development, that website URL is http://localhost:3001
• the CLI opens a dedicated onboarding URL shaped like /cli?device=<hostname>&backend=<backend-url>
• the website redirects that request into the onboarding token page for that Mac
• After sign-in, the website generates an OpenCore onboarding token for the signed-in user.
• You paste that token into the terminal when opencore onboard asks for it.
• if you already generated a still-valid onboarding token earlier, you can paste that existing token
• press Escape at the token prompt to cancel onboarding cleanly
• OpenCore keeps that device signed in locally until you explicitly log out.

Hosted Auth and Account Sessions

OpenCore uses a backend-issued device session for the local Mac runtime.

Current onboarding auth flow:

1. run opencore onboard
2. OpenCore opens the hosted website onboarding URL in your browser
3. the URL resolves into the website's /cli onboarding entry route
4. sign in or sign up there if needed
5. the website generates an onboarding token for that request
6. copy the token from the website
7. paste the token into the terminal
8. OpenCore exchanges that token for a device session and continues onboarding

This is the current onboarding flow. The old opencore setup command no longer exists.

Useful commands:

opencore onboard
opencore login
opencore account
opencore whoami
opencore auth status
opencore logout

opencore login still exists for hosted account sign-in flows, but opencore onboard is the main first-run setup command.

opencore account shows:

• signed-in state
• account identity
• device session state
• last sync state
• token usage summary

Permissions

To let OpenCore control your Mac UI, allow your terminal app in:

1. System Settings -> Privacy & Security -> Accessibility
2. System Settings -> Privacy & Security -> Screen Recording

If those permissions are not granted, OpenCore can still do non-UI work such as reasoning, local file work, scheduling, skills, and dashboard operations.

How OpenCore Works

OpenCore has two main runtime roles:

• Manager agent: plans, routes work, uses local tools, edits files, delegates to sub-agents, and answers directly when no execution is needed
• Computer-use agent: performs UI actions on the Mac when a task requires real desktop interaction

Production rule:

• only the main agent can use computer-use
• sub-agents do not control the desktop

Sub-agents are specialist agents with their own local state. They can reason, research, edit local files, coordinate with other sub-agents, and report results back to the main agent.

Local Data Layout

OpenCore stores local state under:

~/.opencore

Main agent files include:

• soul.md
• brain.md
• memory.md
• knowledge.md when enabled
• computer-profile.md
• heartbeat.md
• guidelines.md
• instructions.md
• chat-history.json
• .agents/skills/
• configs/account-session.json
• configs/backend-sync-queue.json

Sub-agents live under:

~/.opencore/sub-agents/<agent-id>/

Each sub-agent has its own:

• soul.md
• brain.md
• memory.md
• knowledge.md
• computer-profile.md
• heartbeat.md
• guidelines.md
• instructions.md
• chat-history.json
• agent.json
• .agents/skills/

Main-agent and sub-agent chat histories are separate.

Mission Chat, CLI, and Dashboard

You can work with OpenCore from:

• the terminal
• the local dashboard
• Telegram, if configured

The dashboard includes pages for:

• Mission Chat
• Account
• Agents
• Scheduled Tasks
• Skills
• Credentials
• Telegram
• Screenshots
• editable agent files such as soul.md, brain.md, memory.md, computer-profile.md, heartbeat.md, guidelines.md, and instructions.md
• knowledge.md when knowledge mode is enabled

Mission Chat behavior:

• if the active agent is working, the dashboard shows that state
• while that agent is running, you cannot send another task to that same agent

The dashboard has a slash-command palette. The CLI does not show a dropdown, but slash commands still execute directly.

Models

During onboarding, you choose the manager agent provider and model.

Supported manager providers include:

• OpenAI
• Anthropic
• Google
• xAI
• DeepSeek
• Moonshot

Examples of supported manager model families include:

• GPT-5 series
• GPT-4o
• OpenAI reasoning models such as o3 and o4-mini
• Codex models
• Claude Sonnet, Opus, and Haiku families
• Gemini Pro and Flash families
• Grok families
• DeepSeek V3 and R1 families
• Kimi K2 families

Useful command:

/models

That shows the current manager model and the current computer-use model configuration.

Backend Sync and Token Usage

OpenCore is local-first.

Behavior:

• local chat history is written first
• backend sync happens after local persistence
• temporary backend failure does not block local task execution
• unsent chat and token-usage events are queued locally and retried later

Synced data in the current release:

• main-agent chat history
• sub-agent chat history
• token usage from provider responses when usage metadata is available

Not synced in the current release:

• credentials
• screenshots
• agent markdown files such as soul.md, brain.md, or instructions.md

Skills

OpenCore supports built-in and external skills.

Main-agent skills are stored under:

~/.opencore/.agents/skills

Each sub-agent also has its own skills directory:

~/.opencore/sub-agents/<agent-id>/.agents/skills

External skills appear automatically in the dashboard when installed in the correct skills folder.

Minimum external skill structure:

• SKILL.md
• optional config.json

Sub-Agents

Sub-agents are persistent specialist agents.

Create them from:

• the CLI
• the dashboard
• natural-language requests to the main agent

Name is required when creating a sub-agent.

Examples:

/new-agent:researcher

/new-agent:planner

After creation:

• the dashboard switches to that sub-agent’s Mission Chat
• OpenCore asks for that sub-agent’s role or purpose
• the first role-definition message configures that sub-agent’s soul.md, brain.md, instructions.md, and guidelines.md

Switching between agents:

/main

/<agent-id>

Useful command:

/agents

Sub-agent rules:

• sub-agents can edit local files
• sub-agents can reason, research, and coordinate with other sub-agents
• sub-agents can send results, errors, and requests for help back to the main agent
• sub-agents do not use computer-use
• only the main agent owns desktop control

When the main agent assigns work to a sub-agent, that delegated task and the sub-agent response appear in that sub-agent’s Mission Chat.

Knowledge, Brain, and Self-Improvement

OpenCore has two persistent learning layers:

• brain.md: always on; stores durable user-specific preferences, relationship continuity, and long-term operating context
• knowledge.md: optional; stores only genuinely new durable lessons

Enable knowledge mode with:

opencore knowledge enable

Or while OpenCore is running:

/knowledge

Check status:

opencore knowledge status

/knowledge-status

knowledge.md is intentionally sparse. OpenCore should write to it only when it learns something genuinely new that it did not already know and has not already recorded.

Secure Mode

Secure mode is off by default.

Toggle it while OpenCore is running:

/secure

Behavior:

• with secure mode off, normal local file work proceeds without approval
• with secure mode on, sensitive local edits outside ~/.opencore can require approval
• edits inside ~/.opencore remain allowed

When approval is required, the dashboard shows Approve and Cancel controls above the Mission Chat text field.

Credentials

OpenCore can store reusable website credentials and defaults.

Capabilities:

• save website login metadata
• save a default email
• save an email provider
• optionally allow automatic email activation for sign-up flows

Passwords and provider tokens are handled more carefully than normal dashboard data and should only be used on a trusted local machine.

Telegram

Telegram is optional.

If connected, you can send tasks from Telegram while the CLI is running. OpenCore validates Telegram token setup and uses long-polling with backoff so transient network failures do not flood the runtime.

Useful commands:

/telegram-reconnect

/telegram-disconnect

Scheduled Tasks

OpenCore can create scheduled tasks and heartbeat checks.

Scheduled work can belong to:

• the main agent
• a specific sub-agent

Useful commands:

/schedules

/check-heartbeat

/unschedule:<schedule-id>

Common Commands

CLI commands:

opencore onboard
opencore engage
opencore account
opencore logout
opencore update
opencore knowledge enable
opencore knowledge status
opencore config show
opencore config set-key openai
opencore config set-key anthropic
opencore config set-key google
opencore config set-key xai
opencore config set-key deepseek
opencore config set-key moonshot

In-session commands:

/models
/agents
/new-agent:<name>
/main
/<agent-id>
/skills
/schedules
/unschedule:<schedule-id>
/check-heartbeat
/knowledge
/knowledge-status
/secure
/telegram-reconnect
/telegram-disconnect
/exit

Update

Update OpenCore with:

opencore update

opencore update updates the full published OpenCore package, including:

• CLI
• dashboard UI
• runtime and agent logic
• prompts and templates
• packaged assets
• shipped dependency versions

You can also install the newest published version directly:

npm i -g @opencoreai/opencore@latest

Troubleshooting

opencore command not found

Install globally again:

npm i -g @opencoreai/opencore@latest

Computer-use does not work

Check:

• Accessibility permission
• Screen Recording permission
• that you are running on macOS

A non-OpenAI manager model fails to start

Check that:

• you selected a supported provider/model during onboarding
• the correct provider API key is configured
• your OpenAI key is still present, since computer-use remains OpenAI-backed

Dashboard data is missing

Make sure OpenCore is actively running with:

opencore engage

Onboarding cannot complete sign-in

Check:

• OPENCORE_BACKEND_URL is correct on the Mac
• the backend service is running
• the backend can reach Neon and Clerk
• CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY, and OPENCORE_PUBLIC_BASE_URL are set correctly on the backend

Account sync or token tracking is missing

Check:

• opencore account
• the device is still signed in
• the backend is reachable from the Mac
• the provider actually returned usage metadata for the request

Release Verification

For maintainers working from the repository:

npm run backend:prisma:generate
npm run verify:release

To run the hosted backend locally:

`npm run backend:start` is only for local backend development. End users do not run a backend locally; they connect to the hosted OpenCore service through the website-issued onboarding token flow.

That verifies the production package path, including build, typecheck, tests, and tarball smoke validation.

License

OpenCore is distributed under the OpenCore Personal Use License 1.0.

It is not open source.

The license prohibits:

• modification
• redistribution
• resale
• creating derivative works
• commercial use

See LICENSE for full terms.