Pilot is a self-hostable founder operating system for discovery, decision, build, launch, and application workflows. This start path gets a founder/developer from a clean checkout to one useful governed workflow without forcing them to understand every operator concern first.

Audience

Use this page if you are a founder, solo developer, or technical evaluator who wants to run Pilot locally, create a workspace, connect the minimum required services, execute one useful workflow, and see what crosses the HELM governance boundary.

Outcome

At the end you should have:

• a local Pilot gateway and web UI;
• PostgreSQL with pgvector running;
• a workspace you can authenticate into;
• one task or workflow queued through Pilot;
• a clear distinction between founder guidance and operator/self-hosting guidance;
• one governed action that produces an allow, deny, escalation, or health signal from the HELM path when configured.

First Workflow Path

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Clone["Clone Pilot"]
        Workspace["Create workspace"]
        Mode["Choose Discover, Decide, Build, Launch, or Apply"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Trust["HELM-governed action check"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Setup["Run setup script"]
        Task["Run one useful workflow"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Output["Artifact, receipt, or denial reason"]
    end

    %% Operational Flow Edges
    Clone --> Setup
    Setup --> Workspace
    Workspace --> Mode
    Mode --> Task
    Task --> Trust
    Trust --> Output

    %% Premium Styling Rules
    style Setup fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Task fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Trust fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Output fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Clone["Clone Pilot"]
        Workspace["Create workspace"]
        Mode["Choose Discover, Decide, Build, Launch, or Apply"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Trust["HELM-governed action check"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Setup["Run setup script"]
        Task["Run one useful workflow"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Output["Artifact, receipt, or denial reason"]
    end

    %% Operational Flow Edges
    Clone --> Setup
    Setup --> Workspace
    Workspace --> Mode
    Mode --> Task
    Task --> Trust
    Trust --> Output

    %% Premium Styling Rules
    style Setup fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Task fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Trust fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Output fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

Source Truth

This onboarding page is backed by:

• docs/self-hosting.md
• docs/env-reference.md
• docs/api.md
• docs/helm-integration.md
• docs/security.md
• services/gateway/
• services/orchestrator/
• packages/db/
• packs/founder_ops.v1.json

If a command here differs from setup scripts or service code, update this page.

1. Install The Minimal Stack

git clone https://github.com/Mindburn-Labs/pilot.git
cd pilot
bash scripts/setup.sh

The setup script checks prerequisites, generates local secrets, starts the database, runs migrations, and tests the API. The gateway runs on port 3100; the web UI runs on port 3000.

For local development without Docker, use the operator-focused Self-Hosting page.

2. Verify Runtime Health

curl http://localhost:3100/health | jq

Expected output includes overall status and checks for the database and job queue. If HELM is configured, health should also show whether the governance sidecar is reachable.

3. Create Or Enter A Workspace

Use the web UI or auth API to create a workspace. Workspace context is the unit for tasks, operators, connector grants, approvals, audit events, and budget policy.

For API-driven setup, request and verify an email code:

curl -sS -X POST http://localhost:3100/api/auth/email/request \
  -H 'Content-Type: application/json' \
  -d '{"email":"founder@example.com"}' | jq

Development mode may return a code directly. Production should send it through the configured email provider.

4. Run One Useful Workflow

Start with a low-risk task:

• Discover: score an opportunity or search knowledge.
• Decide: compare options and produce a decision artifact.
• Build: create a structured task or implementation plan.
• Launch: create a deploy target or launch checklist artifact.
• Apply: draft an application section for review.

For a simple API smoke:

curl -sS http://localhost:3100/api/product/modes | jq

Then create a task from the UI or POST /api/tasks with a workspace ID.

5. Understand The Governed Action

Pilot can run with direct providers for local development, but production should route through HELM. When HELM_GOVERNANCE_URL and HELM_FAIL_CLOSED=1 are set, LLM inference and consequential tool execution are expected to pass through the HELM boundary.

You should see one of four outcomes:

Founder Vs Operator Docs

Troubleshooting