Quick Start

Get Arcana running in under a minute. This guide walks you through installation, provider setup, and your first session.

Step 1 — Install

# One-shot (downloads binary on first run)
npx arcana-ai@latest

# Or install globally
npm install -g arcana-ai
arcana --version

Package name is arcana-ai; the binary is always arcana.

Step 2 — Get Started

Arcana works in two modes:

Bring Your Own Key (BYOK) — Free

Use your own provider API keys directly. Arcana detects them automatically:

# OpenAI
export OPENAI_API_KEY=sk-...

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# Google Gemini
export GEMINI_API_KEY=...

# Or any other supported provider
# See /docs/providers for the full list

Arcana License — Proxy & Cloud Features

For the Arcana proxy (hosted API endpoint), cloud memory sync, and Gateway, you need an Arcana license. This is separate from provider API keys:

# Arcana license for proxy/cloud features
export ARCANA_LICENSE=your-license-key

# Proxy uses your license, not individual provider keys
arcana run --proxy "explain this codebase"

Your license covers proxy access. BYOK mode (direct provider keys) is always free.

Step 3 — Check Health

arcana doctor

This verifies your config, API keys, cache, and runtime environment. Fix any issues it reports before proceeding.

Step 4 — Run

# Interactive TUI session
arcana

# One-shot prompt
arcana run "explain this codebase"

# Or just:
arcana "review open PRs for bugs"

Step 5 — Explore

Inside the TUI, try these slash commands:

Command	What it does
`/help`	List all available commands
`/skills`	Browse and activate skills
`/memory`	Search your memory database
`/compact`	Manually compact the session
`/providers`	Switch model providers mid-session

Optional Setup

arcana console login

Opens a browser for device-flow authentication at arcana.otnelhq.com. Enables cloud memory sync and the proxy API.

Trust Your Workspace

arcana trust

Required if your project has local plugins, tools, or MCP servers. Without trust, project-level extensions are blocked.

Schedule Automation

# Run a code review every 4 hours
arcana cron add --name "review PRs" --schedule "0 */4 * * *" --prompt "review open PRs for bugs"

# Start the cron daemon
arcana cron start

See Cron for full details.

Chat Gateway

arcana gateway

Run Arcana as a bot on Telegram, Discord, Slack, or WhatsApp. See Gateway for setup instructions.

What's Next?

Providers Set up your preferred LLM provider Model Recommendations Choose the best model for your task Skills Load domain expertise on demand Memory Persistent, searchable knowledge base Configuration All config options and env vars Examples Real-world workflows and patterns

Last updated: Jul 24, 2026