Skip to content

Latest commit

 

History

History
93 lines (70 loc) · 3.17 KB

CONTRIBUTING.md

File metadata and controls

93 lines (70 loc) · 3.17 KB

Contributing to Outpost

Development setup

  1. Clone the repo and install dependencies:

    git clone https://github.com/getsentry/outpost.git
    cd outpost
    pnpm install
  2. Copy the environment template and fill in your credentials:

    cp apps/server/.env.example apps/server/.dev.vars
  3. Run D1 migrations locally:

    pnpm -F @jared/server db:migrate:dev
  4. Start the dev server:

    pnpm dev

Project layout

  • apps/server/ — the main Cloudflare Worker + React dashboard
  • apps/server/src/agents/ — Flue 'use agent' modules (Jared + subagents)
  • apps/server/container/ — thin Sandbox image (Phase 2) + Phase 1 Flue app
  • apps/server/src/routes/ — API route handlers
  • apps/server/src/client/ — React SPA (dashboard UI)
  • apps/server/src/lib/ — shared business logic
  • docs/ — Flue migration notes (FLUE_PARITY.md, LORE_GATEWAY.md)
  • packages/ — shared packages (utils, validations)

Code style

  • TypeScript — strict mode, no any unless necessary
  • Biome — linting and formatting (pnpm format)
  • Imports — use @/ path alias for apps/server/src/

Adding a new webhook provider

  1. Create a new file in apps/server/src/routes/webhooks/ (e.g. gitlab.ts)
  2. Implement signature verification and payload parsing
  3. Use ensureSandboxReady() and dispatchPrompt() from @/lib/containers/dispatch for container management
  4. Mount the handler in apps/server/src/routes/webhooks/index.ts
  5. Add any new environment variables to apps/server/src/types/env/base.ts

Adding agent skills

Agent skills live in apps/server/container/skills/ — this is the single source of truth. Each skill is a directory with:

  • SKILL.md — instructions the agent follows when the skill is loaded
  • references/ — optional supporting files the SKILL.md links to
  • SPEC.md — optional authoring-only design notes (not shipped to the sandbox)

The runtime tree apps/server/container/.agents/skills/ (baked into the image and discovered by Flue) is generated from skills/ — it mirrors every file except SPEC.md. After editing a skill, regenerate and commit the result:

pnpm -F @jared/server sync:skills

CI fails if .agents/skills/ is out of date with skills/, so never hand-edit the generated tree.

Database

  • D1 (SQLite) via Drizzle ORM
  • Schema: apps/server/src/db/schema.ts
  • Generate migrations: pnpm -F @jared/server db:generate
  • Apply locally: pnpm -F @jared/server db:migrate:dev
  • Apply production: pnpm -F @jared/server db:migrate:prod

Deployment

pnpm deploy

This runs turbo deploy which builds the Worker, builds the client, pushes the container image, and deploys to Cloudflare.

Key conventions

  • Webhook handlers go in src/routes/webhooks/<provider>.ts
  • Container/sandbox logic goes in src/lib/containers/
  • Provider-specific logic (auth, API clients) goes in src/lib/<provider>/
  • All container communication uses sandbox.exec() — there is no direct network path from the Worker to the container
  • Session data syncs from the container to D1 when the dashboard detail page is accessed (auto-sync)