Free Tier Guide

Arcana is free and open-source. You only pay for the LLM providers you use. This guide shows you how to get the most from Arcana without spending a dime — or spending very little.

Truly Free Options

Ollama (Fully Local, Fully Free)

Run models on your own hardware. No API key, no cost, no data leaves your machine.

# 1. Install Ollama: https://ollama.com
# 2. Pull a model
ollama pull llama3.1:8b
ollama pull codellama:7b

# 3. Arcana auto-detects Ollama
arcana doctor

# 4. Run
arcana run "hello"

Best for: Daily coding, learning, experimentation. Requires 8GB+ RAM.

Google Gemini Free Tier

Google offers free API access with generous rate limits.

# 1. Get free API key: https://aistudio.google.com/apikey
export GEMINI_API_KEY=...

# 2. Run
arcana run "explain this code"

Limits: 15 RPM, 1M tokens/day. Plenty for most personal use.

DeepSeek (Very Cheap)

Not free, but extremely cheap. Often under $0.01 per session.

export DEEPSEEK_API_KEY=...
arcana run "review this PR"

Cost Optimization Strategies

Use a Cheap Utility Model

Arcana uses a secondary model for background tasks (extraction, compaction). Set this to the cheapest option:

{
  "model": "gpt-4o",
  "utilityModel": "gpt-4o-mini"
}

Good cheap utility picks: gpt-4o-mini ($0.15/1M), gemini-2.5-flash ($0.15/1M), deepseek-chat ($0.14/1M).

Compact Early and Often

Lower the compaction threshold to save tokens on long sessions:

{
  "compaction": {
    "auto": true,
    "threshold_percent": 70
  }
}

Use One-Shot Prompts

# Instead of interactive sessions, use one-shot:
arcana run "review the last 5 commits"
arcana run "explain src/utils.js"
arcana run "write tests for UserService"

One-shot prompts use fewer tokens than interactive sessions.

Switch Models for Different Tasks

# Use cheap models for simple tasks
export ARCANA_MODEL=gemini-2.5-flash
arcana run "explain this error"

# Switch to powerful models only when needed
/providers
> select gpt-4o
> complex refactoring task

Free Weekly Session Plan

A structured approach to using Arcana for free on a weekly basis:

Weekly total: ~$0.005 (essentially free)

Free Features

These Arcana features are always free:

• ✅ Memory — local SQLite, FTS5 search
• ✅ Skills — load, search, create custom skills
• ✅ Session history — browse, resume, search past sessions
• ✅ Cron jobs — scheduled automation
• ✅ Theme customization — dark/light themes
• ✅ Workspace trust — project-level permissions
• ✅ Plugin system — extend with custom plugins

What Costs Money

• 💰 API calls — paid to your LLM provider
• 💰 Proxy API — optional hosted endpoint (requires license)
• 💰 Gateway — chat platform adapters (requires Pro/Enterprise)
• 💰 Cloud sync — memory sync across devices (requires license)

How Free Tier Model Routing Works

The free tier proxy (arcana-proxy) provides access to Cloudflare Workers AI models through a multi-provider routing layer. Not every model listed in the catalog will always be available — here's why:

Routing Layers

When you select a Cloudflare model (prefixed with @cf/), the proxy attempts providers in this order:

1. Cloudflare AI Gateway — preferred path. Routes through a caching and analytics layer. Model must exist on Workers AI.
2. Direct Workers AI — fallback if Gateway is unavailable. Same model requirements.
3. OpenRouter — safety net. Falls back to OpenRouter's model catalog if both Cloudflare paths fail.

Why Available Models May Differ

• Not all listed models are online. Cloudflare's Workers AI catalog includes models that may be deprecated, beta, or temporarily unavailable. The proxy serves the full catalog from Cloudflare's docs, but individual models may return errors.
• Gateway 400 errors fail over. If the AI Gateway rejects a request (unsupported model, invalid parameters), the proxy automatically retries through the next provider rather than returning an error to you.
• Model names can change. Cloudflare occasionally updates model identifiers. The proxy refreshes its catalog every 24 hours from the official docs.
• Rate limits apply. Free tier has a 5,000 request daily soft ceiling and 60-minute session windows. Heavy usage may trigger temporary cooldowns.

Checking What's Actually Routing

# See which models are available right now
arcana models

# Check proxy health and active routes
curl https://proxy-arcana.otnelhq.com/v1/models | jq '.data[].id'

# View your current rate-limit status
arcana usage

If a model returns an error, try another. The proxy handles provider failover automatically — a cloudflare-ai-gateway/@cf/deepseek-ai/deepseek-r1-distill-qwen-32b request that fails through Gateway will silently retry through OpenRouter.

Getting Started for Free

# Option 1: Ollama (fully local)
ollama pull llama3.1:8b
arcana

# Option 2: Gemini free tier
export GEMINI_API_KEY=...
arcana

# Option 3: DeepSeek (very cheap)
export DEEPSEEK_API_KEY=...
arcana