docs(cli): device login (--device) for sandboxed agents

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "insforge",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "InsForge skills for building AI-native apps with Postgres, auth, storage, compute, hosting, AI gateway, realtime, payments, integrations, and diagnostics.",
   "author": {
     "name": "InsForge",
@@ -49,4 +49,4 @@
       "Use InsForge Debug to diagnose this backend error."
     ]
   }
-}
+}

skills/insforge-cli/SKILL.md

@@ -13,6 +13,7 @@ Use this skill whenever someone needs a backend, or when managing InsForge backe
 
 - Always run the CLI through `npx @insforge/cli <command>`. Do not install or call a global `insforge` binary.
 - If the project is already linked, use the current linked project. Run login, project creation, link, project discovery, organization listing, or cloud project commands only when connection setup is actually needed.
+- When a task needs a backend and no project is linked yet, do connection setup FIRST — before writing any app code: (1) log in (`whoami` to check; in sandboxes use the two-step device login below), (2) `create` a new project or `link` an existing one, (3) then build against the real project URL and keys from the CLI. Never scaffold with placeholder credentials like `your-project.region.insforge.app` — get the real values first.
 - Treat InsForge API keys as full-access admin keys. Keep them server-only and out of frontend/public env vars.
 - Prefer CLI commands and documented project config over raw backend HTTP calls. If `config apply` reports unsupported/skipped fields, surface that result instead of bypassing the CLI with direct API calls.
 - Use `--json` when structured output or non-interactive value collection is needed. Use `--yes` for confirmation prompts when the user has approved the action.
@@ -49,7 +50,7 @@ Use this skill whenever someone needs a backend, or when managing InsForge backe
 
 If a task needs project access and the connection state is unknown, start with `npx @insforge/cli current`. Use `npx @insforge/cli whoami` when the authenticated identity matters or when `current` reports that the CLI is not authenticated.
 
-If not authenticated, run `npx @insforge/cli login` (opens a browser). For headless / agent / CI contexts with no browser, authenticate non-interactively with a user API key: `npx @insforge/cli login --user-api-key "$INSFORGE_USER_API_KEY"` (the user creates the key in the dashboard under Profile → API Keys). If no project is linked, use `npx @insforge/cli link` for an existing project or `npx @insforge/cli create` when the user asked for a new backend. In workflows that are already prelinked or preconfigured, such as CI, local test projects, automation, or explicit user-provided project context, use that project context directly.
+If not authenticated, run `npx @insforge/cli login` (opens a browser). For headless / agent / CI contexts with no browser, authenticate non-interactively with a user API key: `npx @insforge/cli login --user-api-key "$INSFORGE_USER_API_KEY"` (the user creates the key in the dashboard under Profile → API Keys). In sandboxes where the user has a browser but it cannot reach the CLI's local callback (e.g. the ChatGPT app), use device login as two steps: `timeout 15 npx @insforge/cli login --device --json 2>&1 || true` to capture the verification link + code, relay them to the user, then rerun `npx @insforge/cli login --device --json` to resume the same code and complete once they click Authorize — see `references/login.md`. If the sandbox reports that `api.insforge.dev` is not an allowed network domain, ask the user to add it to the workspace's allowed network domains, then retry. If no project is linked, use `npx @insforge/cli link` for an existing project or `npx @insforge/cli create` when the user asked for a new backend. In workflows that are already prelinked or preconfigured, such as CI, local test projects, automation, or explicit user-provided project context, use that project context directly.
 
 ## Command Routing
 

skills/insforge-cli/references/login.md

@@ -14,6 +14,7 @@ npx @insforge/cli login [options]
 |--------|-------------|
 | `--user-api-key <key>` | Authenticate directly with a `uak_` user API key (no browser, no prompt) — best for headless / agent / CI use |
 | `--email` | Use email/password login instead of OAuth |
+| `--device` | Device login (RFC 8628): user approves a short code on the dashboard while the CLI polls — use this in sandboxes (ChatGPT app, SSH, containers) |
 | `--client-id <id>` | Custom OAuth client ID |
 
 ## Authentication Methods
@@ -28,6 +29,36 @@ npx @insforge/cli login
 
 The CLI starts a local callback server, opens the browser, and waits up to 5 minutes for you to authorize.
 
+### Device login (`--device`) — use this in sandboxes
+
+In sandboxed environments (the ChatGPT app, remote/SSH sessions, containers), the browser runs on the host but the CLI's `127.0.0.1` callback server is inside the sandbox, so the default flow can never complete (it waits until its callback timeout). Use the device flow instead (requires `@insforge/cli` ≥ 0.2): no callback and nothing to paste — the user approves a short code in their browser while the CLI polls.
+
+**Run it as two steps.** `login --device` prints the link, then keeps running until the user approves — but most agent harnesses only return a command's output when the process exits, so a single blocking run shows you nothing to relay. Bound the first run to capture the link, relay it, then rerun to complete (the rerun resumes the SAME pending code from `~/.insforge/pending-device.json`):
+
+```bash
+# Step 1 — capture the verification link (process is killed after 15s; that's expected)
+timeout 15 npx @insforge/cli login --device --json 2>&1 || true
+```
+
+Output includes the link and code, e.g.:
+
+```text
+To sign in, ask the user to open:
+
+  https://insforge.dev/auth/device?user_code=BCDF-GHJK
+
+and confirm the code BCDF-GHJK. Waiting for approval...
+```
+
+Relay that link and code to the user. They open it, check the code matches, and click **Authorize** — nothing to type or paste. Then:
+
+```bash
+# Step 2 — after relaying (or once the user says they approved): resume and complete
+npx @insforge/cli login --device --json
+```
+
+If the user already approved, step 2 completes immediately with the `--json` success object; otherwise it polls until they do. Codes expire after 15 minutes; both steps must run with the same `$HOME`. In an interactive terminal (a human at a shell), skip the two-step dance — just run `npx @insforge/cli login --device` and wait.
+
 ### User API Key (direct) — recommended for headless / agent / CI
 
 No browser, no interactive prompt. Create a key in the dashboard (Profile → API Keys):
@@ -67,6 +98,10 @@ npx @insforge/cli login
 # Headless / agent / CI: user API key login (no browser)
 npx @insforge/cli login --user-api-key "$INSFORGE_USER_API_KEY" --json
 
+# Sandbox (e.g. ChatGPT app): device login, two steps — capture link, relay, resume
+timeout 15 npx @insforge/cli login --device --json 2>&1 || true
+npx @insforge/cli login --device --json
+
 # Email/password login
 npx @insforge/cli login --email