8000 GitHub - anantjain-xyz/wallie-dev: Wallie runs gated, sandboxed coding-agent workflows across product, design, engineering, review, and land stages. · GitHub
[go: up one dir, main page]

Skip to content

About

Wallie runs gated, sandboxed coding-agent workflows across product, design, engineering, review, and land stages.

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

791 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Wallie

License: MIT Try it free at wallie.dev

AI-powered product development automation. Wallie turns a work prompt -- optionally linked to a Linear issue -- into reviewed, staged work. It runs Codex, Claude Code, Cursor, or OpenCode in a GitHub-backed sandbox, preserves a versioned artifact for every stage, and keeps the human approval loop in the dashboard.

Just want to use it? wallie.dev is a free, fully-hosted instance. To run your first task, connect a GitHub repository, a sandbox provider, and your agent credentials. Linear is optional.

Want to run your own? Wallie is open source (MIT). Follow the Self-Hosting guide to deploy your own instance, or the Local Setup section below to hack on it.

After setup, follow the first-task verification walkthrough to review the output and verify the resulting PR.

How It Works

flowchart LR
  member["Workspace member"] --> app["Next.js app and API routes"]
  app --> db["Supabase Auth, Postgres, RLS, Realtime, Storage"]
  app --> reviewRpcs["approve_session_stage / reject_session_stage"]
  reviewRpcs --> db
  app -->|Authenticated wake| worker["Cloudflare dispatcher and Workflows"]
  worker --> db
  worker --> pipeline["processPipelineJob / runStage"]
  pipeline --> sandbox["Sandbox provider"]
  pipeline --> agent["Codex, Claude Code, Cursor, or OpenCode"]
  sandbox --> github["GitHub repo and pull request"]
  worker --> github
  worker --> linear["Linear API"]
  db -. "Realtime" .-> member
Loading

Wallie organizes work into sessions. Each session is pinned at create time to a pipeline -- an ordered, user-configurable list of stages owned by the workspace. Users can exclude stages when starting a session; the selected membership i 10000 s captured with the session while each selected stage's live configuration and position continue to come from the workspace pipeline. Session creation, selected stages, the first queued job, and its queued run are written atomically. Cloudflare dispatches each captured job attempt to a Workflow, which runs the session's current stage and flips it to awaiting_review for a human to approve or reject from the in-app dashboard. The Node daemon remains available for local development.

Stages are not hardcoded. A workspace can edit, add, remove, or reorder them from settings. Every new workspace is seeded with a default plan → build pipeline so the UX works out of the box, but each stage is just a row in pipeline_stages with a slug, position, name, description, prompt template, and approver list. The stock Build stage validates and publishes a PR, then stops for external review and manual merge. Pipelines also carry workspace-editable operating rules that are prepended to every stage prompt. Nothing in the runner distinguishes one stage from another.

A single generic stage runner (processPipelineJob() in src/lib/pipeline/processor.ts, which delegates to an internal runStage() helper) handles every stage:

  1. Render the pipeline operating rules and stage prompt template against the session context (title, prompt, prior stage artifacts, attempt number, and last reviewer feedback).
  2. Restore the job's fixed Git checkpoint and repository in a sandbox on its own attempt branch. The first execution resolves the session's initial base; successor inputs are selected during review handoff and retries reuse their original input.
  3. Run the workspace's configured agent (Codex, Claude Code, Cursor, or OpenCode) inside the sandbox.
  4. Capture safe source changes in private durable storage and save the original artifact in an immutable publication intent. Push and verify an exact retained remote checkpoint, then atomically accept the checkpoint, versioned markdown artifact, and review state. Interrupted publication retries within the original attempt deadline; PR delivery runs independently after adoption.
  5. Flip the session to awaiting_review without making pull-request plumbing a prerequisite for artifact review.

Humans approve or reject artifacts from the in-app dashboard. Approval validates the displayed stage, immutable artifact ID, and version, then advances to the next selected stage by position and queues its job/run with the approved code checkpoint in the same approve_session_stage transaction. Rejection validates the same review identity, records feedback against the reviewed artifact version and enqueues a new job from that exact artifact's code checkpoint, re-running the same stage with {{attempt.feedback}} injected into the prompt. Text-only stages preserve the existing code; automatic retries keep their generation's original input.

Pipeline Flow

create_session_with_first_job RPC
  -> session created (pinned to workspace's default pipeline)
  (current_stage_id = first stage, phase_status = in_progress)
  -> first agent job + queued run created in the same transaction
  -> worker atomically claims the job, then binds its captured attempt to an eligible session/run
  -> runStage() renders prompt, runs agent in sandbox,
     streams run activity, atomically publishes the artifact + awaiting_review + run success,
     best-effort syncs its attempt PR, then completes the owned job
  -> in the dashboard, the reviewer clicks Approve or Request Changes
  -> approve  -> approve_session_stage RPC records approval, advances by position,
                 and enqueues the next job/run atomically
  -> reject   -> feedback recorded for the artifact version;
                 new job re-runs the same stage
  -> repeat until the terminal stage is approved -> session archived

Codebase Walkthrough

A 10-minute tour of the repository, file by file.

Top-Level Map

wallie-dev/
|-- src/
|   |-- app/           -> Next.js routes (pages + API)
|   |-- components/    -> Shared React UI
|   |-- env/           -> Zod-validated env schemas (client/server/deploy)
|   |-- features/      -> Domain modules (sessions, github, settings...)
|   |-- lib/           -> Core libraries (pipeline, auth, supabase...)
|   `-- worker/        -> Background daemon (polls jobs)
|-- supabase/
|   `-- migrations/    -> Baseline schema + forward migrations
|-- docs/              -> Architecture, lifecycle, self-hosting, telemetry, accessibility, and UI guidance
|-- e2e/               -> Playwright flows and performance benchmarks
|-- middleware.ts      -> Auth gate (Supabase session refresh)
`-- AGENTS.md          -> Repository guidelines

Domain Model

Workspace (tenant)
  |-- Members (humans + "wallie" system agent)
  |-- Secrets (encrypted: LINEAR_API_KEY, repository env keys, ...)
  |-- Pipelines (1..N; one flagged is_default; operating_rules_md)
  |    `-- Stages (position, slug, name, description, prompt_template_md,
  |                approver_member_ids[])
  `-- Sessions <- the unit of work
       |-- pipeline_id (pinned at create time; stage rows remain shared, so
       |   edits can change prompts or ordering observed by pinned sessions)
       |-- current_stage_id, current_artifact_version, rejection_count
       |-- phase_status: in_progress | awaiting_review
       |                 | approved | rejected
       |-- optional Linear issue + pinned GitHub repository
       |-- Artifacts (markdown, versioned on
       |              (session_id, stage_slug, version))
       |    `-- Feedback (targets a reviewed stage/version)
       |-- Phase Completions (one row per approved stage; preserves
       |                      stage_slug snapshot for history)
       |-- Pull Requests (one recorded branch/PR per stage branch)
       |-- Jobs (work queue entries; one active job per session)
       `-- Runs (one agent execution; provider, usage, messages, sandbox)

Pipeline = ordered list of stages owned by a workspace. Stage = a row with a prompt template and approver list; one row per stage in pipeline_stages. Session = one end-to-end workflow pinned to a pipeline. Artifact = versioned markdown per (session, stage_slug, version). Run = one agent execution; a rejection produces a new Run on the same stage.

Critical Flow (session enqueue -> shipped)

create_session_with_first_job RPC
      | atomically creates session + first job + first run
      | first-job dedupe key: session:<session_id>:active
      v
Worker scheduler polls agent_jobs --> claim_next_agent_job RPC
      |- atomic, concurrency-aware job claim
      `- processPipelineJob()
           |- start_session_job_attempt validates job/attempt + stage/version
           |- Generic runStage():
           |    * load current stage + prior artifacts
           |    * render prompt_template_md against session
           |    * mint GitHub installation token, spin up sandbox
           |    * run the configured agent runner
           |    * stream events into agent_run_messages
           |    * capture safe source and persist the original publication intent
           |    * push/verify an immutable retained checkpoint (no-code reuses its input)
           |    * adopt_session_checkpoint_publication commits checkpoint + artifact + review + job success
           `- leased maintenance retries publication and synchronizes its attempt PR
      v
[POST /api/sessions/[sessionId]/phase-action]  (from the dashboard)
      |- Approve -> approve_session_stage RPC: records completion,
      |             advances to next stage by position and enqueues
      |             the next job/run in the same transaction
      `- Reject  -> feedback recorded for the artifact version;
                    new job re-runs the same stage

Final deliverables and activity

Artifacts contain only the provider's final deliverable. Progress, tool events, partial output, and the final response remain in Run history.

Provider Final deliverable boundary
Codex codex exec --output-last-message file
Claude Code Successful terminal result.result
Cursor Successful terminal result.result
OpenCode Text parts for the last completed step with reason: stop

If the final deliverable is missing or blank, the stage fails without creating an artifact. Run history retains available output and the failure reason. Provider errors also prevent publication. Usage accounting remains independent of artifact content.

Publication keeps the final deliverable tied to its original run, attempt, artifact version, and source checkpoint. Existing artifacts remain unchanged.

Five Hub Files

If you read only five files to understand Wallie, read these:

# File Role
1 src/lib/pipeline/processor.ts Generic stage runner. Guard session state, render prompt, run agent in sandbox, write artifact/PR. Review handlers.
2 src/lib/pipeline/stages.ts Pipeline + stage loaders. Maps pipeline_stages rows into the runtime stage shape and gathers prior artifacts.
3 src/app/api/sessions/[sessionId]/phase-action/route.ts In-app approve/reject handler. Workspace membership + RLS, calls approval and the shared follow-up command.
4 src/lib/wallie/service.ts Transactional session creation plus job enqueue/run tracking, readiness checks, and deduplication.
5 src/worker/index.ts Background daemon. Bounded scheduler, heartbeat, stall detector, Linear reconciler, and sandbox reaper.

Walkthrough by Domain

Database -- migrations

  • supabase/migrations/20260422000000_init.sql -- the consolidated baseline schema. Every baseline table, RLS policy, trigger, and RPC (approve_session_stage is the star) lives here.
  • Forward migrations cover schema changes added after the baseline was already applied in production. Recent examples add the pipeline dashboard and narrow session-detail RPCs, transactional session creation, server-rendered session-list sorting/repository data, and workspace usage aggregation.
  • src/lib/supabase/database.types.ts -- auto-generated types.

Pipeline (src/lib/pipeline/) -- the brain

The whole module is stage-agnostic. There are no per-phase files; one generic runner drives every user-defined stage by reading rows from pipeline_stages.

  • processor.ts -- generic stage runner. The public entry is processPipelineJob(); its internal runStage() helper renders operating rules plus the stage prompt, spins a sandbox, runs the agent, writes the markdown artifact, and invokes best-effort PR synchronization. Also handles approval. Session command entry points live in src/lib/sessions/.
  • stages.ts -- loaders for pipelines / pipeline_stages, pipeline operating rules, and the prior-stage artifact map used by the prompt template.
  • source-pull-request.ts, archive.ts, and cancel.ts -- canonical PR synchronization and terminal session controls.
  • prompt-safety.ts -- sanitizes untrusted Linear text (prompt injection defense).
  • types.ts -- shared pipeline phase and agent job/run status types. Active-job dedupe keys (session:<session_id>:active) are built in the enqueue SQL RPCs.

The default plan → build seed lives in the internal.default_pipeline_stages() SQL function in the migration -- workspaces can edit, add, remove, or reorder stages from settings, and renderStagePrompt (in src/lib/prompt-templates/) handles the {{session.title}} / {{session.prompt}} / {{artifact.previousStages.<slug>}} / {{attempt.feedback}} placeholders.

Worker (src/worker/) -- the daemon

API Routes (src/app/api/)

agent-runs/[runId]/{retry,cancel}/                              <- retry or cancel runs
sessions/                                                       <- create a session + its first job/run atomically
sessions/[sessionId]/                                           <- title/state, archive/cancel, artifacts, runs
sessions/[sessionId]/phase-action/                              <- in-app approve / reject
sessions/[sessionId]/review-capabilities/                       <- current reviewer authorization/failure state
agent-config/                                                   <- workspace_agent_config mutations (POST/PATCH; RSC reads)
codex/connection/                                               <- Codex device-auth flow + token verify
claude-code/connection/                                         <- Anthropic API key verify
cursor/connection/ + cursor/models/                             <- Cursor sign-in + model discovery
opencode/connection/ + opencode/providers/                      <- OpenCode Zen key + per-provider keys
github/install/ + github/callback/                              <- GitHub App install redirect + signed state
github/webhooks/                                                <- PR + install events
github/refresh-repositories/                                    <- re-sync the installation's repo list
linear/test-connection/                                         <- verify Linear API key
secrets/ + secrets/[key]/                                       <- encrypted workspace creds (POST/DELETE; RSC reads)
workspaces/[workspaceId]/avatar/                                <- storage upload
workspaces/[workspaceId]/members/ + invitations/ + leave/       <- workspace membership lifecycle
workspaces/[workspaceId]/pipeline-dashboard/                    <- bounded dashboard refresh payload
workspaces/[workspaceId]/pipeline/                              <- pipeline + stage editor
workspaces/[workspaceId]/repositories/[repositoryId]/inference/ <- run repo inference
workspaces/[workspaceId]/repositories/[repositoryId]/onboarding/<- per-repo onboarding mutations (POST/PATCH; RSC reads)
workspaces/[workspaceId]/repository-profile/                    <- workspace_repository_profiles editor
workspaces/[workspaceId]/sandbox-capability-check/              <- probe active sandbox-provider readiness
workspaces/[workspaceId]/sandbox-settings/                      <- active provider switch (PATCH; RSC reads)
workspaces/[workspaceId]/sandbox-connections/[provider]/        <- encrypted Vercel/E2B/Daytona connections (PUT/DELETE; RSC reads)
workspaces/[workspaceId]/linear-routing/                        <- workspace_linear_routing mutations (PUT; RSC reads)
workspaces/[workspaceId]/onboarding/ + onboarding/complete/     <- per-workspace setup state
workspaces/[workspaceId]/maintenance/tick/                      <- privileged maintenance trigger

Features (src/features/) -- domain-grouped

  • sessions/ -- session CRUD plus the server-rendered Sessions ledger and artifact-first Review Workbench. list/ owns the searchable/sortable ledger; detail/ owns the narrow review payload, lazy artifact versions, streamed activity, and Realtime reconciliation.
  • pipeline/ -- the review-focused workspace dashboard plus shared pipeline editor primitives. The editor itself is surfaced from Settings and onboarding.
  • github/ -- GitHub App install + sync: service.ts, webhooks.ts, contracts.ts.
  • settings/ -- streamed, category-based workspace settings with isolated client islands for integrations, pipeline, advanced controls, and workspace administration.
  • onboarding/ -- snapshot-backed multi-step setup for GitHub, repository analysis, pipeline, optional Linear, agent/runtime, and final verification.
  • wallie/ -- bounded run history and live run/message activity for the session-detail workbench.
  • workspaces/ -- workspace layout + membership data helpers.
  • workspace-members/ -- member CRUD (model, server functions, types).
  • repositories/ + repository-profile/ -- repo-setup controls and repo-profile editor UI.

Libraries (src/lib/)

  • supabase/ -- admin.ts (service role), server.ts (RLS), browser.ts (anon), middleware.ts, generated database.types.ts.
  • secrets/ -- crypto.ts AES-256-GCM encrypt/decrypt for stored credentials.
  • linear/ -- client.ts GraphQL client.
  • linear-routing/ -- per-workspace rules mapping a Linear issue to a tracked repository.
  • agent-runner/ -- provider dispatch (index.ts) plus per-provider Codex, Claude Code, Cursor, and OpenCode runners that execute the agent CLI through the provider-neutral sandbox handle.
  • agent-config/ -- contracts + parsing for workspace_agent_config (provider, model, recommended defaults).
  • agent-credentials/ -- resolves which user credential a session run should use.
  • codex/, claude-code/, cursor/, and opencode/ -- provider-specific credential validation, delegated auth where supported, and session-owner credential resolution.
  • sandbox/ -- provider registry and Vercel, E2B, Daytona, and in-process fake drivers.
  • sandbox-connections/ -- encrypted provider connections, active-provider selection, URL policy, and mutation locking.
  • sandbox-capabilities/ -- probes sandboxes for required tools/runtimes and persists the result.
  • repo-inference/ -- inspects a connected repo to infer language, frameworks, and install/test/dev commands.
  • repo-onboarding/ -- planner + server state for the per-repo onboarding flow.
  • onboarding/ -- shared contracts and migration helpers for the workspace onboarding pipeline.
  • prompt-templates/ -- renders stage prompts; resolves {{session.*}}, {{artifact.previousStages.*}}, {{attempt.feedback}} placeholders.
  • wallie/ -- job enqueue + run tracking (service.ts) and HTTP helper.
  • maintenance/ -- privileged workspace maintenance operations used by Settings and its API route.
  • performance/ and telemetry/ -- route budgets, server timing, and privacy-safe interaction RUM.
  • vercel-sandbox/ -- Vercel-specific connection compatibility and workspace teardown.
  • workspace-invitations/ and workspace-members/ -- membership lifecycle contracts and data access.
  • storage/ -- Supabase Storage helpers (e.g. workspace-avatar upload).
  • workspaces/, workspaces.ts -- role-based access control.
  • rate-limit.ts, routes.ts, auth.ts, site-config.ts, utils.ts -- loose utilities.

UI

app/
|-- layout.tsx, page.tsx              (root)
|-- login/, auth/                    (public)
|-- onboarding/workspace/             (first-run: create a workspace)
`-- w/[workspaceSlug]/                (protected workspace shell)
    |-- onboarding/                   (GitHub, repositories, pipeline, Linear, runtime, verify)
    `-- (app)/                        (route group with the real product UI)
        |-- (pipeline)/               review-focused dashboard at the workspace root
        |-- sessions/                 list + /[sessionNumber] detail
        `-- settings/                 integrations, pipeline editor, advanced, workspace

components/
|-- app-shell/   (shell, header, sidebar)
|-- auth/        (auth-entry-panel)
|-- landing/     (public product page)
|-- onboarding/  (workspace onboarding form)
|-- shared/      (markdown, icons, status and time primitives)
|-- telemetry/   (production interaction instrumentation)
`-- ui/          (dialogs, menus, feedback, overlays, page primitives)

Mental Model

The codebase is four layers:

  1. Supabase schema defines nouns.
  2. src/lib/pipeline/ is the verb engine.
  3. src/app/api/ is the edge (ingest + ack).
  4. src/worker/ drains the queue.

Everything else is UI glue or integration plumbing.

Tech Stack

Layer Technology
Framework Next.js 16 (App Router) on Vercel
Language TypeScript (strict mode)
UI React 19, Tailwind CSS 4
Database Supabase PostgreSQL 17 with Row-Level Security
Auth Supabase Auth (email magic link + code)
Realtime Supabase Realtime (live session updates)
Storage Supabase Storage (workspace avatars)
AI Codex, Claude Code, Cursor, or OpenCode CLI
Integrations GitHub App (Octokit), Linear GraphQL
Testing Vitest, Playwright, ESLint, Prettier
Package manager pnpm 10
Node >= 22.13

Project Structure

src/
  app/                          # Next.js App Router
    api/                        # Route handlers (webhooks, jobs, auth, secrets)
      agent-runs/               # Retry and cancel pipeline jobs
      sessions/                 # Atomic create + session review/activity routes
      agent-config/             # workspace_agent_config CRUD
      codex/, claude-code/, cursor/, opencode/  # Provider connection / token flows
      github/                   # GitHub App install, webhooks, repo refresh
      linear/                   # Linear API key verification
      secrets/                  # Encrypted credential CRUD
      workspaces/[workspaceId]/ # Pipeline, repositories, onboarding, sandbox check, ...
    auth/                       # Auth flows (callback, email, signout, confirm)
    login/                      # Public auth page
    onboarding/workspace/       # First-run: create a workspace
    w/[workspaceSlug]/          # Protected workspace shell
      onboarding/               # Post-workspace setup
      (app)/                    # Route group with dashboard / sessions / settings
  components/                   # Shared UI (app shell, sidebar, dropdowns, ui primitives)
  env/                          # Zod-validated environment variable schemas
  features/                     # Domain modules (sessions, pipeline, github, settings,
                                #   onboarding, wallie, workspaces, workspace-members,
                                #   repositories, repository-profile)
  lib/                          # Core logic
    pipeline/                   # Generic stage runner, stage loaders, state machine
    supabase/                   # DB clients, auth, middleware, generated types
    secrets/                    # AES-256-GCM encryption for stored credentials
    linear/, linear-routing/    # Linear GraphQL client + per-workspace routing rules
    agent-runner/               # Provider dispatch + coding-agent runners
    agent-config/               # Provider + model parsing for workspace_agent_config
    agent-credentials/          # Picks the user credential for a session run
    codex/, claude-code/, cursor/, opencode/  # Provider token validation + auth flows
    sandbox/                    # Vercel/E2B/Daytona registry (+ fake for tests)
    sandbox-connections/        # Active provider + encrypted connection service
    sandbox-capabilities/       # Probe sandboxes for required tools
    repo-inference/             # Infer language / framework / commands per repo
    repo-onboarding/            # Per-repo onboarding planner + state
    onboarding/                 # Workspace onboarding contracts + helpers
    prompt-templates/           # Stage prompt rendering
    wallie/                     # Job service + HTTP helper
    workspaces/                 # Access control (role-based)
    storage/                    # Supabase Storage helpers
    maintenance/                # Workspace maintenance operations
    performance/, telemetry/    # Route budgets, timings, privacy-safe RUM
    vercel-sandbox/             # Per-workspace Sandbox connection handling
    workspace-invitations/      # Invitation lifecycle
  worker/                       # Background daemon (bounded scheduler, heartbeat,
                                #   stall detector, reconciler, sandbox-reaper)
middleware.ts                   # Next.js middleware: Supabase auth session refresh
supabase/
  migrations/                   # SQL migrations (schema, RLS, triggers, RPCs)
  seed.sql                      # Development seed data
  config.toml                   # Supabase CLI config (local dev)

Local Setup (End-to-End)

This section gets Wallie running locally for development (local Supabase + a tunnel). To deploy a real, internet-facing instance, see the Self-Hosting guide.

Prerequisites

  • Node.js >= 22.13
  • pnpm >= 10
  • Docker (for local Supabase)
  • Supabase CLI
  • A tunnel tool that exposes localhost:3000 to the public internet. ngrok or cloudflared both work. You only need this if you want to exercise GitHub webhooks; Supabase + Linear + the dev UI work without a tunnel.
  • Accounts/access:
    • Codex, Claude Code, Cursor, or OpenCode access for agent runs
    • Optionally, a Linear workspace + personal API key (for linked issue context and reconciliation)
    • A GitHub user or org where you can create a GitHub App (for GitHub integration)

1. Clone and install

git clone https://github.com/anantjain-xyz/wallie-dev.git
cd wallie-dev
pnpm install

2. Start a public tunnel (optional but recommended)

GitHub webhooks need a public HTTPS URL. Start the tunnel first so you have a stable origin to paste into app configs.

# ngrok ngrok http 3000 # cloudflared (quick tunnel) cloudflared tunnel --url http://localhost:3000

Note the HTTPS URL the tunnel prints (e.g. https://wallie-dev.ngrok.app). It replaces http://localhost:3000 in NEXT_PUBLIC_APP_URL and in every third-party app config below. If you restart the tunnel and get a new URL, update .env.local and the GitHub app settings to match.

3. Start local Supabase

supabase start

This boots a local Postgres 17, GoTrue (auth), Realtime, and Storage stack via Docker. Migrations in supabase/migrations/ are applied automatically. The CLI prints values you need in the next step:

  • API URL -> NEXT_PUBLIC_SUPABASE_URL
  • anon key -> NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
  • service_role key -> SUPABASE_SECRET_KEY

Re-run supabase status any time to recover these. Reset the local DB with supabase db reset.

4. Configure environment

cp .env.example .env.local

Fill in the required values. Integration variables can be left blank until you complete the GitHub app setup below.

Variable Required Description
NEXT_PUBLIC_APP_URL Yes Public app origin (e.g. https://wallie-dev.ngrok.app, or http://localhost:3000)
NEXT_PUBLIC_SUPABASE_URL Yes From supabase start output
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY Yes Supabase anon / publishable key
SUPABASE_SECRET_KEY Yes Supabase service role key
WALLIE_ENCRYPTION_KEY Yes Hex (64+ chars) or base64 (43+ chars) secret used for AES-256-GCM at-rest encryption
GITHUB_APP_ID GitHub GitHub App "General" -> "App ID"
GITHUB_APP_CLIENT_ID GitHub GitHub App Client ID for installation ownership authorization
GITHUB_APP_CLIENT_SECRET GitHub GitHub App client secret (server only)
GITHUB_APP_PRIVATE_KEY GitHub PEM contents from "Generate a private key" (PKCS#1 or PKCS#8; escape newlines as \n if quoted)
GITHUB_WEBHOOK_SECRET GitHub The webhook secret you set when creating the GitHub App
VERCEL_TOKEN Dev/Ops Optional operator token for non-session helper sandboxes or local testing. Wallie session sandboxes use the workspace Vercel connection saved in Settings.
VERCEL_TEAM_ID Dev/Ops Optional Vercel team for the operator token. Workspace session sandboxes do not read this env var.
VERCEL_PROJECT_ID Dev/Ops Optional Vercel project for the operator token. Workspace session sandboxes do not read this env var.
WALLIE_SANDBOX_IMPL No Set to fake for tests/local development; production provider selection is workspace-scoped.
WALLIE_ENABLED_SANDBOX_PROVIDERS No Comma-separated rollout allowlist; defaults to vercel,e2b,daytona.
WALLIE_DAYTONA_API_URL_ALLOWLIST No Exact HTTPS Daytona self-hosted API base URLs; Daytona Cloud is always allowed.
WALLIE_TIMING_LOGS No Set to 1 in a canary to emit server-loader timing logs.
WALLIE_TIMING_LOG_PATH No Optional JSONL file for those records. A write failure does not fail the request.
WORKER_MAX_CONCURRENT_JOBS No Maximum jobs one worker process runs concurrently (default 10); per-workspace limits still apply.
WORKER_JOB_TIMEOUT_MS No Hard deadline per claimed attempt, including setup and cleanup (default 1800000; positive integer up to 30 minutes).

Generate WALLIE_ENCRYPTION_KEY with e.g. openssl rand -hex 32.

Workspace-scoped secrets (LINEAR_API_KEY, repository env keys, etc.) and Vercel/E2B/Daytona sandbox connections are not environment variables -- they are entered through the app's Settings UI and stored encrypted in the database. Per-user agent credentials are also entered in Settings and stored encrypted separately.

Configure agent provider

Workspaces choose the agent provider and model in Settings -> Integrations. Supported providers are Codex, Claude Code, Cursor, and OpenCode. Codex defaults to gpt-5.6-sol; Claude Code defaults to claude-opus-4-8[1m]; Cursor defaults to auto and discovers the models available to the connected account; OpenCode defaults to opencode/gpt-5.6-sol. Codex users can connect a ChatGPT subscription with the Codex device-code flow, paste a Business/Enterprise Codex access token, or paste an OpenAI Platform API key; Claude Code users connect by pasting an Anthropic API key; Cursor users complete Sign in with Cursor, which mints an encrypted, expiring user API key through the Cursor SDK; OpenCode users save an OpenCode Zen API key and, for custom provider ids such as opencode-go/glm-5.3, a matching per-provider API key. The Wallie worker must be running for Cursor sign-in to progress.

5. Create a GitHub App

Go to https://github.com/settings/apps -> New GitHub App (or your org's equivalent under Settings -> Developer settings).

  • Homepage URL: $PUBLIC_URL
  • Callback URL: $PUBLIC_URL/api/github/callback (keep "Request user authorization (OAuth) during installation" off -- Wallie starts a separate OAuth ownership check after the setup callback)
  • Setup URL (required post-install redirect): $PUBLIC_URL/api/github/callback
  • Webhook
    • Active: yes
    • URL: $PUBLIC_URL/api/github/webhooks
    • Secret: any strong random string -- put the same value in GITHUB_WEBHOOK_SECRET
  • Permissions -> Repository
    • Contents: Read and write (clone/push stage branches and repository-onboarding commits)
    • Pull requests: Read and write (open/update setup and session-stage PRs and track their state)
    • Checks: Read-only (read current check runs and their source Apps)
    • Commit statuses: Read-only (read current commit status contexts)
    • Actions: Read-only (verify the workflow event behind GitHub Actions checks)
    • Administration: Read-only (inspect applicable classic branch protection)
    • Metadata: Read-only (mandatory; GitHub enables it automatically)
  • Permissions -> Organization: Members: Read-only (verify that the connecting GitHub user owns the organization). Existing installations must approve this permission change.
  • Subscribe to events: Check run, Check suite, Status, Pull request, Pull request review, Pull request review comment, Pull request review thread, and Push. The installation and installation_repositories events are delivered automatically by GitHub and are handled at /api/github/webhooks.
  • Where can this GitHub App be installed? Only on this account (for local dev).

Existing installations must approve new repository permissions before PR verification can use them. Missing access is recorded explicitly; it never implies that checks or repository rules passed. See PR verification and the read-only permission audit. Updating these instructions does not change an installed App or production settings.

After creation:

  1. Copy App ID -> GITHUB_APP_ID, Client ID -> GITHUB_APP_CLIENT_ID, and generate a client secret -> GITHUB_APP_CLIENT_SECRET.
  2. Click Generate a private key, download the .pem, and put its contents in GITHUB_APP_PRIVATE_KEY (PKCS#1 and PKCS#8 PEM are both accepted). If you inline it into .env.local, replace real newlines with \n and quote the value.
  3. From your workspace's GitHub settings, start Install GitHub App, choose the repositories, and complete the separate GitHub authorization screen. Stay signed in to the same Wallie account and browser throughout the ten-minute flow. You must be a Wallie workspace owner/admin and the GitHub personal-account owner or an active organization owner. Repository collaborators and organization members cannot connect installation-wide access.

Wallie verifies ownership before saving a connection. The browser-bound flow is single-use, uses PKCE, and stores only a hash of state and an encrypted verifier; OAuth access and refresh tokens are never persisted. An installation can belong to only one workspace. Reconnecting the same installation refreshes its metadata; changing installations requires explicit disconnection first. See the upgrade instructions before deploying this change to an existing database.

6. Linear API key (optional)

Linear is pull-only -- no webhook, no OAuth.

  1. Generate a personal API key at https://linear.app/settings/api.
  2. After you create a workspace in Wallie, paste the key into Settings -> Integrations -> Linear. Saving the key automatically calls POST /api/linear/test-connection.

7. Start the dev server

pnpm dev

The app runs at http://localhost:3000 and is reachable at your tunnel origin. Keep it running.

8. Start the worker

In a second terminal:

pnpm worker

The worker heartbeats into worker_heartbeats, uses the concurrency-aware claim_next_agent_job RPC to fill its bounded scheduler, and runs the generic stage runner. Without it, jobs stay queued and nothing progresses past in_progress.

9. First run

  1. Open http://localhost:3000, sign up / log in via Supabase Auth.
  2. Create a workspace, then complete its onboarding: connect GitHub, analyze/select a repository, review the pipeline, optionally connect Linear, connect the agent/runtime, and verify setup.
  3. Use Settings -> Sandbox provider later to connect or switch Vercel, E2B, or Daytona. Other credentials and repository connections remain under Settings -> Integrations; the pipeline editor lives under Settings -> Pipeline.
  4. Create a session from the Sessions ledger, watch the worker claim its first job, then approve or request changes on the resulting artifact from the Review Workbench.

Tunnel: what must be publicly reachable

Integration Endpoint Why
GitHub POST /api/github/webhooks App install and PR event deliveries
GitHub App GET /api/github/callback Browser redirect from github.com
Linear -- (pull only) Wallie calls Linear, never vice versa
Supabase -- (local Docker) App and worker connect to localhost

Troubleshooting

  • GitHub webhook 401 -- GITHUB_WEBHOOK_SECRET in .env.local doesn't match the value in the GitHub App. GitHub's Advanced -> Recent Deliveries panel shows the exact error.
  • Session stays in in_progress forever -- worker isn't running, the worker cannot reach Supabase, or agent/Sandbox/GitHub credentials are missing or invalid. Check pnpm worker logs and the session activity panel.
  • RLS errors during local dev -- confirm SUPABASE_SECRET_KEY is the service role key (not the anon key) and that supabase start finished applying migrations.

Scripts

Command Description
pnpm dev Start Next.js dev server
pnpm build Production build
pnpm start Start production server
pnpm worker Start the bounded-concurrency background worker
pnpm test Run unit/integration tests (Vitest)
pnpm test:watch Run Vitest in watch mode
pnpm test:e2e:onboarding Build and run onboarding mutation-request Playwright coverage
pnpm test:e2e:responsive Build and run responsive/touch Playwright coverage
pnpm test:e2e:session-prefetch Build and verify session-detail prefetch behavior
pnpm test:benchmark:interaction Build and run the interaction RUM benchmark
pnpm test:benchmark:content-visibility Build and run the content-visibility benchmark
pnpm lint Lint with ESLint (zero warnings)
pnpm lint:fix Auto-fix lint issues
pnpm format Format with Prettier
pnpm format:check Check formatting
pnpm typecheck TypeScript type check
pnpm db:types Regenerate local Supabase database types
pnpm db:types:check Compare generated local schema types with the committed file without rewriting it
pnpm analyze:authenticated-bundle Analyze authenticated-route client bundles
pnpm check:route-budgets Check built route bundles against committed byte budgets
pnpm check:cloudflare Native worker types, workerd tests, and Wrangler build
pnpm check Full pre-PR gate: check:fast + unit tests + check:cloudflare

Architecture Notes

Use the documentation index to find the guide for your task.

For ownership boundaries and dependency direction, see Architecture. For session/job transition detail, see Pipeline and worker lifecycle.

Multi-tenancy

Tenant-owned data rows are scoped to a workspace_id, and Supabase RLS policies enforce isolation. A database trigger (enforce_session_refs) validates session FK consistency across workspace boundaries.

Concurrency

Job claims are atomic and concurrency-aware through claim_next_agent_job. Phase approvals use compare-and-swap semantics: approve_session_stage only succeeds if the unarchived session is in awaiting_review at the displayed stage, artifact ID, and version. Approval recording, published predecessor completion, stage advancement, and next-job/run enqueue commit together. The processor's final in_progress → awaiting_review update is scoped to an unarchived session that is still generating. Rejection uses reject_session_stage: it locks the session row and applies feedback, enqueue, and rejected in one transaction, so a concurrent approval serializes on that lock and re-validates phase.

Deduplication

Linear-linked sessions are deduplicated on (workspace_id, linear_issue_id); sessions without a Linear issue are not subject to that constraint. All enqueue paths use session:<session_id>:active and a session-scoped unique active-job index. Linear additionally records source state-span receipts: repeated polls and unrelated issue edits cannot requeue reviewed work, while an actual leave/return can apply once.

Security

  • Integration credentials are encrypted at rest with AES-256-GCM
  • GitHub webhooks are signature-verified
  • Production stage prompts enforce a typed trust boundary: runStage() classifies trusted control text and untrusted session data before renderStagePrompt(), which crosses each value into renderer strings through verifyPromptBoundary(). Untrusted values are wrapped in collision-free boundary markers before template rendering; new prompt inputs must be explicitly classified with trustedPromptValue() or untrustedPromptValue() and cross through the same verifier.

Realtime

The Review Workbench subscribes to Supabase Realtime changes on sessions, session_artifacts, session_phase_completions, and session_pull_requests. Its activity panel separately watches agent_runs and only the currently relevant agent_run_messages, keeping phase, artifact, PR, and bounded run activity live without shipping the full history in the initial page payload.

Integrations

GitHub

A GitHub App syncs repository metadata, creates repository-onboarding and session-stage branches/PRs, and tracks pull request state. Installations and repositories are stored per workspace.

Webhook endpoint: /api/github/webhooks

Linear

Linear is optional. A linked issue keeps its identifier and URL attached to a session. The worker observes its current state span and applies configured routing once: rerouting, cancellation, and replacement enqueue commit together, preserving published artifact versions. See the lifecycle contract for bootstrap and rollout behavior. The personal API key is stored as an encrypted workspace secret and verified via /api/linear/test-connection; Wallie does not require a Linear webhook or OAuth flow.

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to set up, the checks to run before opening a PR, and conventions. To report a security issue, follow SECURITY.md.

License

MIT © Anant Jain and Wallie contributors.

About

Wallie runs gated, sandboxed coding-agent workflows across product, design, engineering, review, and land stages.

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0