CogniForgeCogniForgeOn-Prem Ready
Documentation · Your path: VS Code on your laptop, everything runs on a rented VM

Set up your engine & workspace — IDE local, execution on a VM

This page covers the two steps that are specific to this path: you keep using VS Code on your own laptop as normal, but it connects over SSH to a small rented server that does the actual thinking and coding — so your laptop can stay light, and the work keeps running even if you close it. It's Part 1 and Part 2 of the full "idea to first pull request" guide — you'll go back and forth between that guide and this one; each note below tells you exactly when.

You'll need a plain Ubuntu server from any cloud provider (DigitalOcean, Hetzner, AWS Lightsail — any is fine; 2 CPU / 4GB RAM or more), a few dollars a month. It needs to stay running and reachable over SSH the whole time CogniForge is working — your own laptop can sleep or close, since it's just the window looking into the VM.

1Set up your engine (the VM)

Your engine is the machine that actually runs your Claude subscription for CogniForge — both the planning documents and, later, the code itself.

1a. Rent and connect to your VM

Once it's created, your cloud provider's dashboard will show you a command like ssh root@your-vm-ip — run that in your laptop's terminal (Mac: Terminal app; Windows: PowerShell) to connect to it. Everything else in Part 1 happens inside that SSH connection. Then install Docker with:curl -fsSL https://get.docker.com | sh

1b. Register the VM with CogniForge

  1. In your project's Settings, go to Execution Targets → Register VM.
  2. Click Register — you'll get a one-time install command. Copy it.
  3. Paste and run that command inside your SSH session. It installs CogniForge's own small background agent and registers this machine.
  4. Back in CogniForge, refresh Execution Targets — within seconds it should show Online. If it doesn't, re-check Docker is actually running.

1c. Install Claude Code and sign in with your subscription

  1. Still in your SSH session, run:curl -fsSL https://claude.ai/install.sh | bash
  2. Run claude, choose "Claude account with subscription" (not API key), and follow the on-screen link to sign in with your Claude.ai account in a browser. Paste the code back into the terminal when asked. This login is saved on the VM.

1d. Tell CogniForge to use it

  1. Go to Admin → AI providers → Add custom model (this part is tenant-wide, not project-specific).
  2. Choose the provider adapter "Claude Code on your build VM (dev mode — your own subscription)", leave the base URL box empty, set the model identifier to sonnet (or opus if your subscription includes it), and set every price field to 0. Save.
  3. Go to Admin → Model routing and set this new model as the primary model for every agent listed. This makes every part of CogniForge's own thinking — planning documents and, later, code — run on your subscription.
Engine ready. Go back to the main guide and do steps 3–4 (review/approve your plan, then create and connect your repository) — then come back here for Part 2 below.

2Set up your coding workspace

This is where VS Code — on your own laptop — connects to the VM, so the code gets written interactively there using the CogniForge extension.

2a. Connect VS Code to your VM over Remote-SSH

Install VS Code on your laptop as normal (code.visualstudio.com), then install the "Remote - SSH" extension inside it (Extensions panel, search, Install). Press F1, type Remote-SSH: Connect to Host, and enter the same SSH details from Part 1a. A new VS Code window opens — everything from here on happens inside that window, running on the VM, not your laptop.

2b. Get the repository onto the VM

  1. In CogniForge, open your project's Repositories tab and click Clone command next to your repository — copy it. It already has your credentials embedded, which matters for the next step.
  2. In your SSH session (or the VS Code terminal, which is the same thing once connected), paste and run that command. Don't use VS Code's own Clone Repository button for this one — it can sign you in through VS Code's own GitHub account integration, which only your clicks inside VS Code get to use. The headless Claude Code session that implements your tickets later runs as a plain background process with no such integration, and needs the repo's own credentials on disk to push anything — this command is what puts them there.
  3. Back in the Remote-SSH VS Code window, File → Open Folder… and open the folder you just cloned into (on the VM's filesystem).

2c. Install the CogniForge extension

  1. In CogniForge, go to Admin → IDE integrations and click Download extension (.vsix) (download it onto your laptop — VS Code will offer to install it into the remote window automatically).
  2. In the Remote-SSH VS Code window, open the Extensions panel, click the … menu at the top, choose Install from VSIX…, and pick the file you downloaded.

2d. Connect it

  1. In CogniForge, click your avatar → API keys → New API key, give it a name, copy the key it shows you (only shown once).
  2. In VS Code, click the CogniForge icon in the activity bar, enter your platform URL and paste the key, click Connect. It should turn green and say Connected.
  3. Click Connect Claude ↔ Platform. If this fails saying claude can't be found, the CLI isn't on PATH for the remote host's extension host — re-check Part 1c ran on the VM itself, not your laptop.
Workspace connected. Keep the Remote-SSH window's connection alive (your laptop can sleep — the VM keeps running) whenever you want tickets to be worked, and continue with step 5 of the main guide.
Set up your engine & workspace — IDE on your laptop, execution on a VM — CogniForge Docs