Operations

Local development

Install the monorepo, configure local services, and run the workspace development stack.

Use a local source checkout when contributing to LegionCode or testing deployment changes. Hosted product users do not need the monorepo.

Prerequisites

  • Node.js 20 LTS
  • pnpm 9
  • Git
  • a Cloudflare account for remote bindings and sandbox work
  • a Postgres database reachable through Cloudflare Hyperdrive
  • a GitHub OAuth application for authentication testing

Install

bash
1git clone https://github.com/Puneet-Pal-Singh/LegionCode.git
2cd LegionCode
3pnpm install

Run baseline checks before changing code:

bash
1pnpm lint
2pnpm check-types
3pnpm check:boundaries

Configure

Create apps/brain/.dev.vars from its example and provide GitHub OAuth, session, and credential-encryption secrets. A typical local configuration is:

dotenv
1GITHUB_REDIRECT_URI=http://localhost:8788/auth/github/callback
2FRONTEND_URL=http://localhost:5174
3MUSCLE_BASE_URL=http://localhost:8787
4BYOK_CREDENTIAL_ENCRYPTION_KEY=<64-character-hex-key>
5BYOK_CREDENTIAL_ENCRYPTION_KEY_VERSION=v1

Generate encryption material with openssl rand -hex 32. Never commit .dev.vars.

Configure the Web endpoints in a local .env file when defaults do not match:

dotenv
1VITE_BRAIN_BASE_URL=http://localhost:8788
2VITE_MUSCLE_BASE_URL=http://localhost:8787
3VITE_MUSCLE_WS_URL=ws://localhost:8787

Run and verify

Start each service in its own terminal:

bash
1pnpm --filter @shadowbox/secure-agent-api dev  # 8787
2pnpm --filter @shadowbox/brain dev             # 8788
3pnpm --filter @shadowbox/web dev               # 5174

Verify runtime fingerprints before testing a task:

bash
1curl http://localhost:8787/api/debug/runtime
2curl http://localhost:8788/api/debug/runtime

The public site and docs can be developed independently:

bash
1pnpm --filter @shadowbox/landing dev
2pnpm --filter @shadowbox/docs dev

Use the Cloudflare Pages local commands from deployment when you need to test edge functions, /agents/ routing, /docs/ routing, or the Cloud waitlist form.

PreviousData and storageNextDeployment