Local-Only Mode

Local-only mode processes all events, generates incidents, and builds debug bundles entirely on your machine. No data leaves your system, no network calls are made, and no account is required.

When to Use Local-Only

• Solo development — you're the only developer on the project
• Air-gapped environments — network access is restricted
• Evaluation — trying DebugBundle before connecting to cloud
• Privacy-sensitive projects — data must not leave the machine
• Offline work — no internet available

Setup

Initialize your project in local-only mode (the default):

debugbundle setup

This creates .debugbundle/local/connection.json with:

{
  "mode": "local-only",
  "cloud_project_id": null,
  "cloud_base_url": null,
  "environments": {
    "local": { "delivery": "local-only" },
    "development": { "delivery": "local-only" },
    "staging": { "delivery": "local-only" },
    "production": { "delivery": "local-only" }
  }
}

Workflow

1. Capture Events

Run your application with an SDK configured. Events are written as NDJSON files to .debugbundle/local/events/:

# Or ingest log files directly
debugbundle ingest ./logs/app.log --format debugbundle-ndjson

2. Process Events

Process captured events into incidents and bundles:

debugbundle process

This runs the full pipeline locally: normalize, fingerprint, group into incidents, and generate debug bundles.

3. View Incidents

debugbundle incidents --source local

4. Inspect Bundles

debugbundle inspect inc_local_01H...

5. Watch for New Events

Monitor a log file and process events as they arrive:

debugbundle watch ./logs/app.log --format debugbundle-ndjson

Local Storage Layout

.debugbundle/local/
├── events/           # Raw event NDJSON files
│   ├── 2026-03-24T10-00-00-000Z_batch_001.ndjson
│   └── ...
├── incidents/        # Grouped incident state
│   ├── inc_local_01H.../
│   │   ├── incident.json
│   │   └── events/
│   └── ...
└── bundles/
    └── local/        # Generated debug bundles
        ├── bnd_local_42.json
        └── reproductions/
            └── bnd_local_42_repro.json

Limitations

Upgrading to Connected Mode

When you're ready for team features, run:

debugbundle connect

See Connect to Cloud for the full flow. Your local investigation artifacts remain available under .debugbundle/local/.

Next Steps

• Project Setup — Setup overview
• Connect to Cloud — Enable cloud features
• CLI Local Workflow — Full local CLI workflow