Local-Only Mode

Local-only mode processes events, generates incidents, and builds debug bundles on the machine or storage volume where the SDK writes files and the CLI runs. No data is sent to DebugBundle Cloud, no account is required, and no hosted service is needed.

When to Use Local-Only

• Solo development — you're the only developer on the project
• Air-gapped environments — network access is restricted
• Self-managed servers — operators can install the CLI and keep .debugbundle/ on persistent storage
• 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 event batch 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.

Self-Managed Server Workflow

Local-only can run on a production or staging server you control, but the workflow is server-local:

1. Install the SDK in local-only/file-transport mode on the server.
2. Install the CLI on the same server, or mount/sync .debugbundle/ to a machine where the CLI can run.
3. Keep .debugbundle/local/events/, .debugbundle/local/state.json, and .debugbundle/bundles/local/ on persistent storage if the runtime is containerized.
4. Run debugbundle process there to generate bundles.
5. Let your agent inspect incidents through the local CLI, MCP local tools, or the generated bundle files.

This gives you DebugBundle's core workflow without DebugBundle Cloud. Hosted cloud is still the recommended path when you need centralized production visibility, alerts, webhooks, remote probes, team access, or durable retention for ephemeral infrastructure.

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

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