Documentation · Getting started

Set up a build VM

All code generated for your project is built and tested on a machine you control — the build VM. Your source never runs on shared infrastructure, and the VM never needs to accept incoming connections: it dials out to the platform, so it works behind NAT, a home router, or a corporate firewall.

What counts as a VM? Any Linux machine with Docker: a cloud instance, an office server, or a spare computer. Requirements: docker and docker compose installed, outbound internet access, and ~2 CPU / 4 GB RAM or better for comfortable test runs.

1Get a registration token

In your project, open Settings → Execution Targets → Register VM. The platform shows a one-time registration token and the install command. Tokens are single-use — if you reinstall later, generate a fresh one.

2Install the agent on the VM

Copy the install command from that screen into a terminal on the VM. It:

Downloads the CogniForge agent (a small Python service).
Registers with your token and stores its credential locally.
Installs a systemd service so the agent starts on boot.

Re-installing over a running agent? Stop the service first (sudo systemctl stop cogniforge-agent) — the installer enables the service but won't restart one that's already running with old code.

3Verify it's online

Back in Settings → Execution Targets, the VM should show online within seconds. It sends a heartbeat continuously; if the machine sleeps or loses network, the platform marks it offline and queues nothing to it.

What runs on it — and what doesn't

Runs on the VM: workspace checkouts of your repo, dependency installs, builds, unit tests, end-to-end stacks (docker compose), and the final commit/push jobs. All inside disposable containers with per-VM dependency caches, cleaned up after each run.
Never on the VM: platform credentials or AI provider keys. Model calls run server-side; the VM only ever sees your own repository and a scoped clone URL.
Optional: install Claude Code on this same VM to power the platform with your own Claude subscription — see Use your Claude subscription.