Project Setup

Configure your DebugBundle project with profiles, connection modes, and environment settings.

Every DebugBundle project lives in a .debugbundle/ directory at your repository root. This directory contains all configuration, local event storage, and generated bundles.

Directory Structure

Path	Purpose
`.debugbundle/profile.json`	Project architecture and workflow profile
`.debugbundle/local/connection.json`	Cloud connection and delivery settings
`.debugbundle/local/events/`	Raw local event files
`.debugbundle/local/state.json`	Grouped local incident state
`.debugbundle/local/browser-relay-spool/`	Durable browser relay spool for connected mode
`.debugbundle/bundles/local/`	Generated local bundles
`.debugbundle/bundles/local/reproductions/`	Generated local reproduction artifacts
`.debugbundle/bundles/cloud/`	Downloaded cloud bundles

Getting Started

Initialize a project with the CLI:

debugbundle setup

This creates the local scaffold with a profile.json based on your repository structure and a .debugbundle/local/connection.json file defaulting to local-only mode.

Configuration Files

File	Purpose	Reference
`profile.json`	Project architecture, services, infrastructure, workflows, and agent hints	Profile
`local/connection.json`	Cloud mode, delivery settings, environment config	Connect to Cloud

If your browser frontend and backend API are separate services, follow the canonical Split Frontend & Backend setup path after the initial scaffold.

Operating Modes

DebugBundle supports two operating modes:

Mode	Description	Best For
Local-only	Processing happens where the SDK writes files and the CLI runs. No DebugBundle Cloud.	Solo development, air-gapped environments, controlled servers
Connected	Events can be sent to DebugBundle Cloud for team-wide visibility.	Teams, CI/CD, production monitoring

See Local-Only Mode and Connect to Cloud for detailed guides.

Environment Delivery

In connected mode, you control which environments send events to the cloud and which stay local:

{
  "environments": {
    "local": { "delivery": "local-only" },
    "development": { "delivery": "local-only" },
    "staging": { "delivery": "local-only" },
    "production": { "delivery": "cloud-enabled" }
  }
}

This lets you keep local and pre-production investigation fully offline while sending production events to the cloud for team visibility. If you intentionally keep production local-only, run the CLI on the server or storage volume where .debugbundle/local/events/ is written.

Next Steps

Split Frontend & Backend — Relay ownership, browser endpoint, and deployment guidance
Profile Configuration — Full project schema and validation
Local-Only Mode — Offline-first development and self-managed server-local processing
Connect to Cloud — Enable cloud delivery
Capture Policy — Control what events are captured