Choosing a Model

Bahulam supports a wide range of language models. Which one you should use depends on your task, budget, and whether you bring your own keys.

Platform Default

If you use Bahulam with the platform default (no API key needed), you get DeepSeek V4 Flash — a fast, capable model included with your plan. The platform handles routing, caching, and billing automatically.

The platform also manages sub-agent routing. Explorer-style agents use fast, low-cost models for read-only context gathering, while planner and verification agents can use stronger reasoning models when policy allows it.

Named Modes

The platform maps intent to a pinned model so you don’t have to remember slugs:

Set a mode from the REPL:

/model fast
/model thinking

Or at launch:

bahulam --model thinking

Which concrete model each mode maps to is a platform decision and can change without your action — that’s the point. Choosing a mode also preserves the prompt cache, since everyone in the fleet runs the same pinned model.

Curated Platform Catalog

/model list shows the harness-validated models — those the platform has tested with the Bahulam prompt stack, with cost profiles tuned in the gateway. Each row shows the model ID, a credit badge (~N cr/M in), and the tiers that can select it.

Picking a model outside the curated list prints a warning:

! deepseek/deepseek-fake-model is not harness-validated for the platform
  route — cost/quality untuned. See /model list.

BYOK skips this check entirely — your key, your models.

How the catalog reaches the CLI: the CLI reads the shipped snapshot from the installed runtime bundle first (so /model list works offline), then a background refresh from GET /api/models overlays any drift. Force a fresh pull with /model refresh; the command prints the fetch source, total model count, curated model count, and refresh time before showing the catalog. Use /model status to see the current catalog source and counts without changing your selections. To stay entirely offline, set BAHULAM_MODEL_CATALOG_OFFLINE=1.

Session Overrides

Session /model picks (including named modes and the --route flag) are mirrored into ~/.bahulam/config.json under model_config, model_mode, and route_preference. They survive restarts and are read by the bundled runtime as a fallback before hardcoded defaults.

The persistence is strictly session-driven — refreshing the catalog with /model refresh never rewrites these keys. Use /model clear to reset all overrides, or /model clear <role> to reset a single role.

At launch, precedence is: --model / --route CLI flags → ~/.bahulam/config.json persisted picks → backend profile default → platform fallback.

Tier Ladder: Pro / Plus / Max

Bahulam has three paid tiers, each with increasing credits and entitlements.

Credits are consumed per token processed through the platform gateway. Different models cost different credit amounts — faster/cheaper models cost fewer credits per token.

BYOK (Bring Your Own Key) lets you connect your own provider key. Model calls still route through Bahulam Gateway for a consistent execution path, but the provider bills your key directly and platform model credits are not used.

Fast Model Quotas

On the platform default, sub-agents are automatically routed to the most cost-effective model for each role:

• Explorer (read-only search, grep, file listing) — uses a fast, cheap model with large context (e.g., DeepSeek V4 Flash, Gemini 2.5 Flash)
• Planner (architecture design, reasoning) — uses a capable reasoning model (e.g., Claude Sonnet, DeepSeek V4 Pro)

These sub-agent calls are included in your plan’s credits. You can customize which models are used for each role in Settings.

When to Use BYOK

BYOK makes sense when:

• You already have API keys with Anthropic, OpenAI, or OpenRouter
• You want access to specific models not available on the platform default (e.g., Claude Opus, GPT-4.1, Gemini 2.5 Pro)
• You want to use your own billing — platform model credits are not consumed when BYOK is active
• You need provider-specific model access while keeping Bahulam Gateway traces, usage accounting, and policy enforcement

Setting up BYOK

1. Go to Settings → API Keys on bahulam.ai
2. Add your API key for the provider you want to use
3. Select the model you want from the available list

You can also set the key via environment variable:

export OPENROUTER_API_KEY="sk-or-v1-..."
bahulam

Available Models

The full model list is available in the Settings page and can be filtered by provider, cost, and capability.

Sub-Agent Model Routing

Bahulam uses a multi-agent architecture. When you give it a task:

1. Primary agent — owns the turn, final answer, edits, and tests
2. Explorer — reads files, searches code, gathers context
3. Planner / verifier / debugger — handles a bounded specialist pass
4. Primary agent — synthesizes the handoff and continues

Each role can use a different model. By default, read-only agents use a fast/cheap model and reasoning-heavy agents use a more capable model. You can customize these in Settings → Models and in user-defined agent YAML.

See Agents & Sub-Agents for the YAML shape and execution flow.

Recommended combinations: