Skip to content
Foundry

Quickstart

This guide takes you from a fresh clone to a running Foundry instance. Target time: under 15 minutes.

  1. Clone the repository and install dependencies

    Terminal window
    git clone https://github.com/qdhenry/Foundry.git
    cd Foundry
    bun install

    Bun resolves all workspace dependencies across apps/web, packages/ui, convex, agent-service, agent-worker, and sandbox-worker.

  2. Copy the environment template

    Terminal window
    cp .env.example .env.local

    Open .env.local and fill in the minimum required values:

    Terminal window
    # Convex (filled automatically by `bunx convex dev` on first run)
    NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
    CONVEX_DEPLOYMENT=dev:your-deployment
    

    # Clerk
    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_key
    CLERK_SECRET_KEY=sk_test_your_key
    

    # Agent service (local dev default)
    AGENT_SERVICE_URL=http://localhost:3001

  3. Configure Clerk

    In your Clerk dashboard:

    • Copy the Publishable Key and Secret Key into .env.local.
    • Enable Organizations under Settings > Organizations.
    • You will configure the webhook endpoint after Convex is running.

  4. Start the Convex backend

    Terminal window
    bunx convex dev

    On first run, the Convex CLI prompts you to:

    • Log in to your Convex account
    • Create a new project (or link to an existing one)
    • Deploy the schema and server functions

    Once complete, it outputs your deployment URL. Copy this into NEXT_PUBLIC_CONVEX_URL in .env.local.

  5. Set the Anthropic API key in Convex

    In the Convex Dashboard, navigate to your project’s Settings > Environment Variables and add:

    VariableValue
    ANTHROPIC_API_KEYYour Anthropic API key (sk-ant-...)

  6. Start the frontend

    Open a second terminal:

    Terminal window
    bun run dev

    This starts the Next.js dev server on http://localhost:3000.

  7. Sign in via Clerk

    Open http://localhost:3000 in your browser. Clerk’s authentication flow handles sign-up and sign-in. Create an account and an organization — the organization becomes your Foundry tenant.

  8. Verify the setup

    After signing in, you should see the Programs page. The page will be empty since no programs exist yet. If you see the programs list without errors, your Foundry instance is running.

Section titled “Running all services (recommended)”

The quickstart above runs two processes (Convex + Next.js). For full functionality including AI inference and sandbox execution, run all four:

Terminal window
bun run dev:zellij

This opens a multi-pane terminal layout with all services running simultaneously.
ServicePortPurpose
Next.js3000Frontend (React, App Router)
Convex—Backend (WebSocket, hot-reload)
Agent service3001AI inference sidecar (Express, Claude Code auth)
Sandbox worker8788Cloudflare sandbox execution (Wrangler local dev)

Troubleshooting

Section titled “Troubleshooting”

Convex dev fails to start

  • Confirm Node.js 20+ is installed: node --version
  • Ensure you are logged in: bunx convex auth

Clerk sign-in redirects loop

  • Verify NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY are set in .env.local
  • Ensure Organizations are enabled in the Clerk dashboard

“Not authenticated” errors after sign-in

  • Check that the Convex deployment URL matches between .env.local and the running Convex dev process
  • Confirm Clerk JWT integration is configured in the Convex Dashboard under Auth

Port 3000 already in use

  • Kill the existing process: lsof -ti:3000 | xargs kill -9

Next steps

Section titled “Next steps”