Adding an InsForge backend to your project

When the user asks for a backend (auth, database, storage, functions, AI), follow this workflow. It gives the agent a working backend in two commands with no human signup step.

Critical: always use npx @insforge/cli

NEVER install the CLI globally (npm install -g @insforge/cli). Always run commands via npx:

npx @insforge/cli

This ensures the latest version is always used without global install issues (permissions, PATH, node version mismatches).

1. Create a trial project

POST https://api.insforge.dev/agents/v1/signup
Content-Type: application/json

{"projectName": ""}

Response (201):

{
 "accessApiKey": "ik_...",
 "projectId": "...",
 "appkey": "...",
 "name": "-",
 "region": "",
 "projectUrl": "https://..insforge.app",
 "dashboardUrl": "https://insforge.dev/dashboard/project/",
 "claimUrl": "https://insforge.dev/claim/claim_...",
 "trialExpiresAt": "2026-..."
}

Persist accessApiKey, projectUrl, and claimUrl. You'll need all three.

Cold-start wait (~4s with warm pool, up to ~60s without). Fresh trial projects take a moment before the backend is reachable. With a warm pool hit it's only a few seconds; on a miss it's around a minute. Before the first CLI command — or before handing the user a URL — poll projectUrl until it returns anything other than 503. Cap the wait at 3 minutes; anything longer means the project is stuck provisioning, which isn't something the agent should wait out:

PROJECT_URL=""
for i in $(seq 1 90); do
 code=$(curl -sS -o /dev/null -w '%{http_code}' --max-time 5 "$PROJECT_URL")
 [ "$code" != "503" ] && [ "$code" != "000" ] && { echo "ready ($code)"; break; }
 sleep 2
done

If the loop exhausts, surface the error to the user and stop. Do not call /agents/v1/signup again automatically — that would orphan the stuck project and bill a second one. If the user says "try again," treat that as a new request: delete .insforge/, call signup again, link with the new credentials.

2. Link the CLI to the trial project

Two paths — pick based on whether the user's ask matches a pre-built InsForge template.

Pre-built templates

Each of these is a working app wired to InsForge, with a schema migration included where applicable. They take minutes, not hours.

Option A — Template match: link with --template

Pass --template to link. The CLI creates a subdirectory, clones the template, wires .env.local (including the public anon key, which it fetches from the project), applies the schema migration when present, and runs npm install — all in one command.

npx @insforge/cli link \
 --api-base-url  \
 --api-key  \
 --template chatbot

Interactive mode prompts for the directory name (default insforge-...