cloud-agent-starter

name	cloud-agent-starter
description	Minimal starter runbook for Cloud agents to install, run, and test Ham quickly. Covers backend/frontend startup, chat gateway modes, Cursor key setup, browser runtime checks, and how to keep this skill current as new runbook knowledge is found.

Cloud Agent Starter — run + test Ham fast

When to use

• First run in a fresh Cloud workspace
• Any task that needs local app startup and quick health checks
• Any task that touches chat/gateway modes, browser runtime, or Cursor API wiring

Cloud Agent / HAM VM Git policy

HAM VM and Cursor Cloud / ephemeral workspaces are not the owner’s canonical checkout. main is read-only here for pushes — but you are expected to push feature branches and open PRs when landing work.

You may:

• create a branch, commit scoped changes, git push -u origin <branch>, gh pr create into main for code/product changes.
• skip gh pr create only when the mission is report-only/read-only, or when the operator said no PR / dry run only.

You must not:

• git push origin main (upstream main included).
• --force, --force-with-lease, or any rewrite of refs/heads/main on the remote.
• treat this clone as SSOT for main or “repair main” from here.

If asked to push main, return MAIN_PUSH_REQUIRES_OWNER_LOCAL_CONTEXT, I can push this to a branch and open a PR instead., then create branch + PR per AGENTS.md → Cloud Agent / HAM VM Git policy.

Never use git push --force* targeting remote main.

1) Fast setup (do this first)

From repo root:

1. Install backend deps:
   • python3 -m pip install -r requirements.txt
2. Install pytest (not in requirements.txt):
   • python3 -m pip install pytest
3. Install frontend deps:
   • npm install --prefix frontend
4. Create local env file:
   • cp .env.example .env

2) Authentication + mode defaults (practical)

Chat mode (feature flag you usually set first)

• HERMES_GATEWAY_MODE=mock (default safe local mode; no external key needed)
• Real model calls:
  • Set HERMES_GATEWAY_MODE=openrouter
  • Set OPENROUTER_API_KEY=...
• External OpenAI-compatible gateway:
  • Set HERMES_GATEWAY_MODE=http
  • Set HERMES_GATEWAY_BASE_URL=...
  • Optional: HERMES_GATEWAY_API_KEY=...

Cursor Cloud API key ("login")

• Option A (env): set CURSOR_API_KEY in .env.
• Option B (API, persists server-side):
  • POST /api/cursor/credentials with { "api_key": "..." }
• Verify key identity:
  • GET /api/cursor/credentials-status

Write-protected routes (set only when needed)

• HAM_SETTINGS_WRITE_TOKEN for project settings apply/rollback
• HAM_RUN_LAUNCH_TOKEN for operator launch_run turns
• HAM_SKILLS_WRITE_TOKEN for Hermes skills install apply

3) Start the app (backend + frontend)

Use two terminals/tmux panes:

• Backend (repo root), recommended for dashboard + Vite smoke:
  • python3 scripts/run_local_api.py — loads optional .env, defaults HERMES_GATEWAY_MODE=mock, keeps API-side Clerk enforcement off via HAM_LOCAL_DEV_LOOSE_CLERK (default 1; set HAM_LOCAL_DEV_LOOSE_CLERK=0 to tighten).
• Backend (alternate, bare uvicorn):
  • python3 -m uvicorn src.api.server:app --host 0.0.0.0 --port 8000 — set gateway + Clerk variables yourself when hitting authenticated workspace routes with a strict policy.
• Frontend (frontend/):
  • npm run dev

Quick smoke checks:

• curl -sS http://127.0.0.1:8000/api/status
• curl -sS -I http://127.0.0.1:3000
• Open http://127.0.0.1:8000/docs

4) Testing workflows by codebase area

A) Context Engine (src/memory_heist.py)

• Run focused suite:
  • python3 -m pytest tests/test_memory_heist.py -q
• Use when touching repo scan, config discovery, git diff capture, or session compaction.

B) Hermes reviewer/supervision (src/hermes_feedback.py)

• Run focused suite:
  • python3 -m pytest tests/test_hermes_feedback.py -q
• Use when touching review loop, critique prompts, or learning-signal shaping.

C) Droid registry/execution metadata (src/registry, src/tools)

• Run focused suite:
  • python3 -m pytest tests/test_droid_registry.py -q
• Use when changing droid records, defaults, or registry behavior.

D) API surface (src/api/*)

Run backend, then smoke test key routes:

• curl -sS http://127.0.0.1:8000/api/status
• curl -sS -X POST http://127.0.0.1:8000/api/chat -H 'content-type: application/json' -d '{"messages":[{"role":"user","content":"hello"}]}'
• curl -sS http://127.0.0.1:8000/api/context-engine

Mode-specific check:

• In mock mode, /api/chat should return a "Mock assistant reply..." response.

E) Frontend (frontend/)

• Type/lint gate:
  • npm run lint --prefix frontend
• Manual check:
  • Open http://127.0.0.1:3000
  • Confirm dashboard loads and can call backend (/api/status, chat UI flows)

F) Browser runtime (src/api/browser_runtime.py)

Prereq for full runtime behavior:

• python3 -m playwright install chromium

Minimal checks:

• curl -sS http://127.0.0.1:8000/api/browser/policy
• Create a session:
  • curl -sS -X POST http://127.0.0.1:8000/api/browser/sessions -H 'content-type: application/json' -d '{"owner_key":"local-dev"}'

Useful env flags:

• HAM_BROWSER_ALLOW_PRIVATE_NETWORK=true|false
• HAM_BROWSER_ALLOWED_DOMAINS=...
• HAM_BROWSER_BLOCKED_DOMAINS=...
• HAM_BROWSER_SESSION_TTL_SECONDS=...

G) Managed Cursor missions (Cloud Agent feed)

Use when you need managed mission APIs or the mission feed path (not the same as Bridge RunStore or ControlPlaneRun).

• Roadmap + shipped vs partial: docs/ROADMAP_CLOUD_AGENT_MANAGED_MISSIONS.md
• Workspace chat → operator launch routing (smoke): docs/HAM_CLOUD_AGENT_ROUTING_SMOKE.md
• Feed projection (SDK bridge vs REST): env HAM_CURSOR_SDK_BRIDGE_ENABLED (true / 1 / yes → live bridge in src/integrations/cursor_sdk_bridge_client.py + bridge.mjs; otherwise REST projection). Rollback in prod: set to false without changing launch URLs — see roadmap § "Rollback control".
• Launch token (deploy / browser): HAM_CURSOR_AGENT_LAUNCH_TOKEN — see docs/DEPLOY_CLOUD_RUN.md § "Cloud Agent launch token".
• List missions (read): curl -sS http://127.0.0.1:8000/api/cursor/managed/missions (requires working Cursor credentials when exercising live Cursor-backed rows).

PR / docs checklist (prevent duplicate Cloud Agent PR churn)

HAM launch prompts inject cursor-agent-v2 PR hygiene; match it in Cursor Cloud agent behavior.

Ephemeral / VM: default to branch + PR (see Git writes above). Owner-local workflows in AGENTS.md may still avoid PRs when the owner is driving from a known canonical path.

1. Plan/report first. For code/product landings from Cloud/VM, open a PR when work is complete. Do not avoid gh pr create just to stay on main remotely.
2. No unsolicited docs-only PRs — edit canonical Markdown in-place where possible (AGENTS.md, README.md, roadmap/mission-aware docs).
3. Before a docs PR: gh pr list --repo OWNER/REPO --state open --limit 50 — if overlaps exist → report OVERLAPPING_DOCS_PR_FOUND instead of spawning another duplicate.
4. One mission ⇒ at most one PR when PRs were explicitly authorized.
5. Regenerate CURSOR_EXACT_SETUP_EXPORT.md only via python scripts/build_cursor_export.py; do not hand-edit as a prose duplicate.
6. Deeper governance: AGENTS.md → Cloud Agent PR hygiene section.

5) Common quick fixes

• python3 -m pytest ... fails with No module named pytest:
  • Run python3 -m pip install pytest
• uvicorn not found in PATH:
  • Use python3 -m uvicorn ... instead of bare uvicorn.
• Chat endpoint errors in non-mock mode:
  • Re-check HERMES_GATEWAY_MODE and matching credentials in .env.

6) Keep this skill updated

When you discover a new reliable runbook trick:

1. Add it under the correct codebase area above (do not add a generic dump section).
2. Include one concrete command and one expected result.
3. Prefer focused tests (tests/test_*.py) over full-suite runs.
4. Remove stale steps immediately when routes/env names change.
5. Keep this file minimal; move deep architecture details to AGENTS.md/VISION.md.