Getting Started

This guide walks you through installing Embercore, generating your first marketing plan, executing it, and viewing results in the dashboard.

Time to first plan: ~5 minutes.

Prerequisites

Tool Version Why
Go 1.23+ Builds the engine binary
Node.js 20+ (see .nvmrc) Runs the Next.js dashboard
pnpm 9+ Workspace package manager
Git any Clone the repo

You also need an API key from at least one supported provider:

1. Clone and install

git clone https://github.com/embercore-labs/embercore.git
cd embercore
pnpm install

Build the Go engine:

cd packages/engine
make build    # produces ./embercore-engine

Optionally, add the binary to your PATH:

# Linux / macOS
cp embercore-engine /usr/local/bin/embercore

# Windows (PowerShell)
Copy-Item embercore-engine.exe C:\tools\embercore.exe

2. Configure your API key (BYOK)

Embercore never stores your keys — you bring your own. Set them via environment variables or a .env file.

Option A: Environment variables

export ANTHROPIC_API_KEY="sk-ant-..."

Option B: .env file

Copy the example and fill in your key:

cd packages/engine
cp .env.example .env

# .env
ANTHROPIC_API_KEY=sk-ant-...

# Optional
# CHECKPOINT_TIMEOUT_MINUTES=30
# MAX_ITERATIONS_PER_STAGE=3

Environment variable reference

Variable Required Default Description
ANTHROPIC_API_KEY Yes (if Anthropic) — Anthropic API key
OPENAI_API_KEY Yes (if OpenAI) — OpenAI API key
EMBERCORE_PROVIDER No anthropic Provider to use: anthropic or openai
EMBERCORE_MODEL No Provider default Override the LLM model
OPENAI_BASE_URL No — Custom base URL for OpenAI-compatible APIs
CHECKPOINT_TIMEOUT_MINUTES No — Timeout for checkpoint approval
MAX_ITERATIONS_PER_STAGE No — Max iteration loops per stage

3. Generate your first plan

embercore plan "Launch a B2B SaaS product for team task management"

This sends your brief to Athena (the planner agent), which generates a structured YAML plan with checkpoints, agent assignments, and dependencies.

The plan is automatically saved to the local SQLite database (~/.embercore/data.db). You’ll see output like:

Plan saved: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Plan command flags

Flag Description
--model <model> Override the LLM model
--provider <name> Use anthropic or openai
-o, --output <file> Write YAML to file instead of stdout
--no-save Skip persisting to the database

Save to a file

embercore plan "Launch a newsletter for developers" -o my-plan.yaml

4. Execute the plan

Run a plan by its ID (from step 3) or by file path:

# By ID
embercore run a1b2c3d4-e5f6-7890-abcd-ef1234567890

# By file
embercore run my-plan.yaml

Hermes (the executor agent) walks each checkpoint in topological order. At each step, you’ll be prompted to approve:

── Checkpoint: research
   Agent:  Apollo
   Action: Generate market research report

   Approve? [y/n/skip]:

Run command flags

Flag Description
--auto-approve Skip all checkpoint prompts
--model <model> Override the LLM model
--provider <name> Use anthropic or openai

5. Check status

# List all plans
embercore status

# Show detail for a specific plan
embercore status <plan-id>

The detail view shows the plan metadata, latest run status, and checkpoint history.

6. Resume a paused run

If a run was paused (you rejected a checkpoint, or the process was interrupted), resume it:

embercore resume <run-id>

Hermes picks up from the last completed checkpoint automatically.

7. View in the dashboard

Start the Next.js web dashboard:

# From the repo root
pnpm dev

Open http://localhost:3000. The dashboard lets you:

8. Use as an MCP server

Embercore exposes its agents as MCP (Model Context Protocol) tools, making them callable from Claude Desktop, VS Code, Cursor, and other MCP clients.

stdio mode (default)

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "embercore": {
      "command": "embercore-engine",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

HTTP mode (remote / Claude.ai)

embercore-engine -http -addr :8080

The MCP endpoint is available at http://localhost:8080/mcp.

See MCP Integration Guide for the full list of tools and client configurations.

Next steps