Documentation · AI & cost

Three ways to power your AI: platform, tenant, or your own subscription

Every AI call CogniForge makes — implementation, architecture, code review, document generation — is routed through a model, and that model's key is owned by exactly one of three parties: the platform, your tenant, or your own Claude subscription. This guide walks the whole journey, sign-up to a successful first AI call, for each. It complements — not replaces — AI models & routing (the mechanics of routing/fallback/circuit-breaking) and Cost & analytics (where to watch spend); this page is about who's responsible for what, end to end.

1Sign up and create your first project

Before any of the three scenarios below apply, you need a tenant and a project to route models into:

Sign up and create (or join) a tenant.
Create your first project — see Create your first project for the full greenfield flow (idea → Understanding → Constitution → SAD → board).

None of the three model-ownership scenarios below block project creation or document generation's early stages — but at least one of them must be working before any ticket actually gets implemented, since implementation is itself an AI call.

2Decide which scenario fits you

Scenario	Who owns the key	Who pays	Setup effort	Best for
Platform-managed	The platform	Your tenant, metered per token against a prepaid balance	Low — request access, top up, done	Getting started fast, no provider account of your own
Tenant-managed (BYOK)	Your tenant (or a self-hosted model you run)	Your own provider account directly (Anthropic, OpenAI, …), or free if self-hosted	Medium — obtain a key, register it	Cost control, existing provider contracts, self-hosted/local models
Your own subscription	Whoever logged in on a build VM	Nobody — your existing Claude Pro/Max subscription, $0 metered	Medium — CLI login on a build VM, register a pointer	Already paying for Claude Code personally, want zero marginal AI cost

These aren't mutually exclusive. Every agent (implementation, architecture, QA, …) is routed to a model independently, with an optional fallback — see step 6. A common setup is a BYOK or subscription model as primary with a platform model as fallback, or vice versa.

3Scenario A — Platform-managed

Steps & responsibilities (you): Ask your platform administrator to grant your tenant access to a platform model — this isn't automatic on sign-up. Once granted, request a prepaid top-up from Admin → AI providers → Prepaid usage → Request top-up; a platform admin reviews and approves it before your balance updates. From then on, route agents to the platform model in Admin → Model routing (pick from the "Platform-shared" group).

Tasks handled by the platform: A platform superadmin grants your tenant access to specific curated models (this grant is what makes them selectable at all), approves or rejects your top-up requests, and can credit your balance directly. Once granted and funded, the platform runs every invocation, meters it per token against your prepaid balance, and applies its own circuit breaker/fallback resilience automatically.

Configuration & setup: None on your side beyond the access request and top-up — no key to generate, no provider account to create. This is genuinely the lowest-effort path once access is granted.

Model connectivity & auth: Entirely internal to the platform — credentials never touch your tenant's configuration or any build VM. You never see or manage an API key for this path.

Operational considerations: Your balance is $0 until you request and get a top-up approved — budget for that approval turnaround before you need it, not after a ticket fails. Calls are blocked outright once the balance hits zero (a clear error, not a silent failure). The batch-tier toggle (Admin → AI providers, on by default) gets background document work a 50% discount at no functional cost.

Expected outcome & validation: Admin → AI providers shows a non-zero prepaid balance; Admin → Model routing shows at least one agent routed to a model from the "Platform-shared" group; a test call from the Playground succeeds and appears in Admin → Recent invocations with a real (non-zero) cost.

4Scenario B — Tenant-managed (BYOK)

Steps & responsibilities (you): As tenant admin, obtain an API key from your provider of choice (Anthropic, OpenAI, or an OpenAI-compatible endpoint) — or stand up a self-hosted model (e.g. Ollama) if you'd rather pay nothing per token. In Admin → AI providers, click Add credential (provider + API key, plus a base URL if self-hosted), then Add your own model (pick the provider, give it a display name, and the exact model identifier string your provider expects — e.g. claude-sonnet-4-5 or qwen2.5-coder:7b). Route agents to it in Admin → Model routing (the "Your own models" group).

Tasks handled by the platform: Encrypts and stores your API key (AES-256-GCM) — it's never shown again after saving, not even to you. Meters every call for your own cost visibility even though your provider is billing you directly, not the platform. Applies the same circuit-breaker/fallback resilience as any other model.

Configuration & setup: One credential per provider, one or more custom model entries pointing at it. There's no separate "test credential" step — the key is validated implicitly on its first real invocation.

Model connectivity & auth: The platform calls your provider directly using your stored key — a straight API integration, no intermediary hop. If a call fails with an auth error, the credential is automatically flagged invalid so you know to check it, rather than retrying silently.

Operational considerations: A monthly spend cap can be set on your BYOK usage — but only by a platform administrator, not by you; you can view the cap and your current spend (and toggle the batch-tier discount) under Admin → AI providers, but ask your platform admin if you need one set or changed. If you want resilience against your own provider having an outage, set a platform or subscription model as the fallback for critical agents (step 6).

Expected outcome & validation: The credential shows no "invalid" flag in Admin → AI providers; your model appears under "Your own models" in the routing dropdown; a Playground test call succeeds and its ledger entry in Admin → Recent invocations shows billed_via: byok.

5Scenario C — Your own subscription (Claude Code on a build VM)

Read this scoping note first: despite the name, this isn't bound to an individual CogniForge user account. The Claude CLI's login lives on whichever build VM you run claude login on — think "this build VM has a subscription attached" rather than "this person's login is attached." A VM is registered against exactly one project (Register VM lives in that project's own Settings), and its subscription only ever serves that project — another project in the same tenant cannot use it, even to fall back onto. If you want more than one project powered by your subscription, register a separate VM (and run claude login again) for each one.

Steps & responsibilities (you): Open a terminal on your build VM (SSH or directly), install the Claude CLI (curl -fsSL https://claude.ai/install.sh | bash), run claude, choose "Claude account with subscription" (not API key), and complete the browser sign-in / device-code flow. Back in CogniForge, go to Admin → AI providers → Add custom model, choose the "Claude Code on your build VM" adapter, leave the base URL empty, set the model identifier (sonnet or opus), and set all prices to $0. Route agents to it — with a paid fallback recommended (step 6). Full walkthrough: Use your Claude subscription.

Tasks handled by the platform: Tracks, per build VM, whether the claude CLI is present and logged in (via the VM agent's heartbeat) and dispatches each invocation to this project's own registered VM specifically — never a different project's VM, even one that's online and capable, in the same tenant. Runs it through the exact same routing/ledger/circuit-breaker pipeline as platform and BYOK models — it just happens to cost $0 because you set the prices that way, not because the pipeline is skipped.

Configuration & setup: A build VM already registered and online (see Set up a build VM), the CLI installed and logged in on it, and one custom-model pointer registered in CogniForge — that's the entire setup surface.

Model connectivity & auth: The OAuth-style login happens entirely outside CogniForge, directly between the CLI and Anthropic — CogniForge stores no credential for this path at all, only a pointer to "call this project's own registered VM, if it has Claude Code available." Never a platform/provider API key on the VM, matching the same rule build VMs follow for everything else.

Operational considerations: Subject to your Claude subscription's own usage limits, not unlimited — a burst of ticket activity can still hit a rate/usage ceiling your subscription itself imposes. If the VM is offline, or Claude Code isn't available on it right then, the call fails and — if you configured one — a fallback model takes over automatically; set one for any agent you can't afford to have silently blocked. Registering a new build VM means repeating the CLI login on it; nothing carries over automatically between VMs.

Expected outcome & validation: A Playground test call against this model succeeds and shows a cost of exactly $0.000000 in Admin → Recent invocations — that ledger entry existing at all confirms the VM, the CLI login, and the model pointer are all wired up correctly.

6Validate and combine — routing, fallbacks, and what to check

Whichever scenario(s) you set up, the same place ties them together: Admin → Model routing. Each of CogniForge's fixed agents (implementation, architecture, QA, security, devops, technical debt, business understanding) gets its own primary model and an optional fallback model — pick from platform-shared or your own models for either slot, in any combination. A primary that fails (an error, or a model that's been failing repeatedly and is in cooldown) automatically retries against its fallback; every attempt is logged separately in the invocation ledger.

Cheapest resilient setup: your subscription or a self-hosted model as primary (free), a platform or BYOK model as fallback (so a VM/subscription hiccup doesn't stall work).
Lowest-effort setup: platform-managed only, no fallback needed until you have a reason to add one.
Cost-controlled setup: BYOK as primary with a platform admin-set monthly cap, a platform model as fallback so hitting the cap degrades gracefully instead of blocking outright.

For ongoing spend visibility across whichever mix you land on, see Cost & analytics.