CogniForgeCogniForgeOn-Prem Ready
Documentation · Guide

Use your own Claude.ai subscription in CogniForge

Normally, CogniForge pays Anthropic for every AI call by the token. If you already pay for a personal Claude Pro or Claude Max subscription, you can have CogniForge use it instead — so developing your project costs you nothing extra. This guide walks you through it from zero. You don't need to know anything about servers or networking; if you can copy-paste commands into a terminal, you can do this.

What you need before starting:
  • A personal Claude Pro or Claude Max subscription (from claude.ai).
  • Your build VM already connected to CogniForge — the same machine that runs your project's tests. If its status shows online under your project's Settings → Execution Targets, you're ready.
  • A way to open a terminal on that VM (for most people: SSH, or just its keyboard if it's a machine on your desk).
Starting completely fresh? Do things in this order. A greenfield project starts generating its Understanding Document the moment you create it — so if you want even those very first documents on your subscription:
  1. First: set up the provider, model, and agent routing (Steps 4–5 below) — this needs no project.
  2. Then: create your project. If document generation can't run yet (your build VM isn't registered until a project exists), the dashboard offers a Retry generation button — no harm done.
  3. Then: register the build VM in the project's Settings, do Steps 1–3 below on it, and hit Retry generation. From that point on, everything — documents included — runs on your subscription. The VM serves your whole workspace, so future projects skip this dance entirely.
Alternatively: keep a platform model routed for the document agents just for project creation, and switch routing afterwards.
Fair-use note: your subscription is a personal product. This feature is dev mode — it powers your own workspace only (CogniForge enforces this), and your subscription's usage limits apply. If you run a lot of work at once, Claude may ask you to slow down; CogniForge will automatically fall back to a normal paid model if you configured one (Step 5).

1Open a terminal on your build VM

Everything in steps 1–3 happens on the VM, not on your laptop. If the VM is a cloud machine, connect with SSH (replace the address with your VM's):

ssh your-user@your-vm-address

If the VM is a computer in front of you, just open its Terminal app.

2Install Claude Code on the VM

Claude Code is Anthropic's official command-line app for Claude. Install it by pasting this one line and pressing Enter:

curl -fsSL https://claude.ai/install.sh | bash

When it finishes, close and reopen the terminal (or run source ~/.bashrc), then check it worked:

claude --version

If you see a version number, it's installed. If you see "command not found", log out of the VM and back in, then try again.

3Sign in with your Claude.ai account

Start the sign-in flow on the VM:

claude

The first time you run it, Claude Code asks how you want to sign in:

  1. Choose the Claude account with subscription option (not the API key option — the whole point is to use your subscription).
  2. It shows a link. Open that link in the browser on your laptop/phone, sign in to claude.ai as usual, and approve.
  3. The browser gives you a code — copy it, paste it back into the VM's terminal, press Enter.

You'll land in an interactive Claude session — type /exit to leave it. The login is saved on the VM; you won't need to repeat this.

Within a minute or two, CogniForge automatically notices that this VM can now run Claude — the VM's agent reports it. There is nothing to configure on the VM itself.

4Tell CogniForge to use it

Now switch to CogniForge in your browser. You'll register your VM's Claude as a model:

  1. Go to Admin → AI Models and click Add custom model.
  2. Choose new provider, and for the adapter pick "Claude Code on your build VM (dev mode — your own subscription)". Give it any name you like (e.g. "My Claude subscription").
  3. Leave the base URL empty — empty means "find my build VM automatically." No addresses, no ports.
  4. For the model: name it (e.g. "Claude Sonnet (my subscription)"), set the model identifier to sonnet (or opus if your plan includes it), and set all prices to 0 — you're not paying per token.

5Route the platform's AI agents to it

CogniForge's work is done by named agents (implementation, architecture, and so on). Each one is routed to a model — point them at yours:

  1. Still in Admin → AI Models, find the agent routing section.
  2. For each agent you want on your subscription, select your new model as the primary.
  3. Strongly recommended: set a normal platform model as the fallback. If your VM is off or your subscription hits its usage limit, CogniForge switches to the fallback automatically instead of stopping your work.

6Check that it works

  1. In Admin → AI Models, scroll to the Playground, pick an agent you routed, type anything, and hit Send.
  2. Look at Recent invocations just above it: a new row should appear with your model's name and a cost of $0.000000. That's your subscription doing the work.

If something doesn't work

  • "No online build VM with Claude Code available" — the VM is off, its agent isn't running, or Claude Code isn't installed/signed in on it. Check the VM shows online in Settings → Execution Targets, then re-run claude --version on the VM.
  • Calls suddenly failing after heavy use — you've likely hit your subscription's usage limit. If you set a fallback model (Step 5), work continues on it automatically; otherwise wait for the limit to reset.
  • Signed into the wrong account? On the VM run claude logout (or claude /logout), then repeat Step 3.
Use your own Claude.ai subscription — CogniForge Docs