--- title: Docs url: https://arcana.otnelhq.com/docs --- # ARCANA Documentation Welcome to the official documentation for **ARCANA** — a self-improving AI agent CLI with skills, memory, gateway, coding, and cron in one terminal. This guide covers installation, configuration, core concepts, and advanced features. ## Quick Start Get up and running in under a minute: ```bash # Quick start (shim downloads binary on first run) npx arcana-ai@latest # Or install globally npm install -g arcana-ai arcana ``` Package name is `arcana-ai`; the binary is always `arcana`. ```bash # 1) Provider key (BYOK) — any supported vendor export OPENAI_API_KEY=sk-... # or ANTHROPIC_API_KEY, GEMINI_API_KEY, etc. # 2) Optional: pair with Arcana console + proxy license arcana console login # https://arcana.otnelhq.com (device seal) # 3) Optional: trust this repo if it has project plugins/tools/MCP arcana trust # 4) Run arcana doctor arcana run "explain this codebase" # or just: arcana ``` ## What is Arcana? Arcana is a **terminal-native AI workbench** that sits one layer above your model providers. You bring your own API keys. Arcana adds session management, memory, tooling, skills, scheduled automation, and multi-platform gateways on top. - **Multi-provider sessions** — Route prompts to different models (GPT-4o, Claude, Gemini, DeepSeek, local Ollama, and 200+ more) from the same session. - **Persistent memory** — Facts extracted during sessions are indexed with SQLite FTS5 and searchable across sessions. Optional cloud sync is available after console login. - **Scoped tool execution** — Shell, filesystem, git, and MCP tools under explicit permission profiles. - **Skills** — Reusable instruction sets (SKILL.md) that give the agent domain expertise. Load automatically or activate with `/skills`. - **Scheduled automation** — Cron jobs that run agent prompts on a schedule from the same runtime. - **Chat gateways** — Telegram, Discord, Slack, and WhatsApp adapters with per-chat sessions and allowlists. - **Governed permissions** — `allow`/`ask`/`deny` rules per tool with glob patterns; risky actions confirm or fail closed. See [Permissions](/docs/permissions). - **Subagents** — delegate work to child sessions with attenuated capabilities and live progress in the TUI. - **Voice input** — fully local push-to-talk dictation (whisper.cpp + Ollama normalization), no cloud required. ## Installation ### Prerequisites - Node.js / npm (or Bun for development) - An API key from any supported provider (OpenAI, Anthropic, Gemini, OpenRouter, xAI, Bedrock, Ollama, etc.) - A modern terminal with Unicode and truecolor support (iTerm2, Windows Terminal, Kitty, WezTerm, etc.) ### Install ```bash npx arcana-ai@latest # or npm install -g arcana-ai arcana --help ``` ### First run Set a provider key via environment variable, then run `arcana doctor` to confirm detection. Start a session with `arcana` or `arcana run "your prompt"`. Type `/help` inside the TUI for slash commands. ## Core Concepts ### Sessions An interactive conversation with one or more models. Sessions are recorded locally with full transcript, token usage, and cost tracking. Resume them with `arcana history resume`. Proxy sessions also appear in the [console dashboard](/console/sessions). ### Providers Arcana auto-detects providers from environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, etc.). No per-vendor command is required. Use `arcana models` and `arcana providers` to inspect what is available. See [Configuration](/docs/configuration) for the full list. ### Memory Structured facts are extracted from conversations and indexed with FTS5. Query with `arcana memory search `. Full details in the [Memory documentation](/docs/memory). ### Tools & MCP Tools let the agent run shell commands, read/write files, use git, and call MCP servers. Permissions are interactive and profile-based. See [MCP & Tools](/docs/mcp). ### Skills Skills are `SKILL.md` files that teach the agent domain-specific workflows. They live in `skills/` (repo) and `~/.arcana/skills/` (user). List and search with `arcana skills list`. See [Skills](/docs/skills). ## Configuration Project settings live in `arcana.json` (or `arcana.jsonc`) in your repository — Arcana walks up parent directories to find the nearest one. Global settings live in `~/.config/arcana/arcana.json`, and project values merge over global ones. The legacy `~/.arcana/config.json` layout still loads (override its root with `ARCANA_HOME`). Environment variables always take precedence for API keys. ```bash # Typical flow export OPENAI_API_KEY=sk-... arcana doctor arcana run "hello" ``` Full reference: [Configuration](/docs/configuration). ## Next Steps Explore the documentation by topic: - [Governance](/governance/) — The complete security kernel — PDP/PEP, capabilities, approvals, RunProof - [Quick Start](/docs/quickstart) — Get running in under a minute — install to first session - [Providers](/docs/providers) — OpenAI, Anthropic, Gemini, xAI, Bedrock, and 30+ more - [Model Recommendations](/docs/models) — Best model for coding, writing, analysis, and budget - [Configuration](/docs/configuration) — Config file, env vars, compaction, trust, and data directory - [CLI Commands](/docs/cli) — doctor, run, console login, trust, gateway, cron, memory, skills - [Gateway](/docs/gateway) — Telegram, Discord, Slack, WhatsApp with allowlists - [Cron](/docs/cron) — Scheduled autonomous agent jobs - [Examples & Cookbook](/docs/examples) — Real-world workflows — code review, refactoring, automation - [Troubleshooting](/docs/troubleshooting) — Common issues and debugging - [Customization](/docs/customization) — Themes, interface voice, and background images - [Voice Input](/docs/voice-input) — Local push-to-talk dictation with whisper.cpp - [Subagents](/docs/subagents) — Parallel delegation with scoped capabilities - [JSON & Exit Codes](/docs/cli-json) — --json envelope and deterministic exit codes for CI