Last updated 2026-06-01 by Kahtaf.

Getting Started

OpenCandle runs as an interactive Pi agent in the terminal and as a local browser GUI. Pi is the bundled local agent runtime that handles model setup, the terminal shell, and saved sessions; OpenCandle adds the financial tools and workflows on top. The CLI is the primary entry point; the GUI is a local workbench for chat, tool discovery, provider status, session history, and financial context.

OpenCandle is read-only research software. It does not place trades, route orders, or provide financial advice.

Requirements

• Node.js ^20.19.0, ^22.12.0, or >=24.0.0 <27
• One supported model provider configured through Pi: OpenAI, Anthropic, or Google
• Optional market data provider keys for expanded coverage

Install

npm install -g opencandle
opencandle

You can also run the latest package without a global install:

npx opencandle@latest

From a source checkout:

npm install
cp .env.example .env
npm start

On Windows Command Prompt, use copy .env.example .env instead of cp .env.example .env. OpenCandle stores local state in ~/.opencandle on macOS/Linux and %USERPROFILE%\.opencandle on Windows unless OPENCANDLE_HOME is set.

On first run, OpenCandle walks through model setup. You can rerun setup later from inside the agent with /setup.

For the fastest successful path, follow First Run. It shows a keyless first prompt, what success looks like, and how to handle common setup failures.

Choose Your Interface

Use the terminal UI when you want the fastest keyboard loop, slash commands, and a plain transcript.

Use the GUI when you want a visual investigation workspace: chat, workflow cards, tool results, provider setup, session history, and financial context in one browser tab.

Both use the same OpenCandle tools and saved session state. You can start in the terminal and later inspect sessions in the GUI.

Run the Local GUI

From a source checkout:

npm run gui

From an installed package:

opencandle gui

Then open http://127.0.0.1:14567. The GUI binds locally and shares Pi sessions through a writer/follower lock so only one process mutates a session at a time.

Good first GUI flow:

1. Ask What is AAPL trading at?
2. Open the catalog with ⌘K on macOS or Ctrl+K on Windows/Linux.
3. Pick a workflow such as Comprehensive Analysis or Compare Assets.
4. Inspect the tool card or drawer to see what data was used.
5. Open the provider tab if the answer says a data source is missing.

See GUI Quickstart for catalog usage, health checks, Tailscale access, and writer/follower behavior.

Configure Providers

Model credentials are handled by Pi. OpenCandle-specific provider keys can come from environment variables or ~/.opencandle/config.json.

Yahoo Finance, CoinGecko, Reddit, SEC EDGAR, DuckDuckGo search, and the alternative.me crypto Fear & Greed index do not require keys.

Example config:

{
  "providers": {
    "alphaVantage": {
      "apiKey": "..."
    },
    "fred": {
      "apiKey": "..."
    },
    "brave": {
      "apiKey": "..."
    },
    "exa": {
      "apiKey": "..."
    },
    "finnhub": {
      "apiKey": "..."
    }
  }
}

Environment variables override ~/.opencandle/config.json. Set OPENCANDLE_HOME to store OpenCandle state somewhere other than ~/.opencandle/.

See Configuration for the complete env var list, config precedence, state files, and GUI host/port settings.

First Investigations

What is AAPL trading at?
Run /analyze NVDA
Compare BTC and ETH over the last month
Show MSFT puts with Greeks
Get CPI from FRED
Add 100 shares of NVDA at 120 to my portfolio, then show my portfolio

OpenCandle should tell you when a provider is unavailable, a key is missing, or a result is degraded. Treat those warnings as part of the answer.

For slash commands, session behavior, and CLI-vs-GUI tradeoffs, see TUI.

Validate a Checkout

npm test
npm run gui:web:build
npm run docs:site:build

Use npm run test:e2e and npm run test:e2e:providers only when you intentionally want tests that hit live providers.