Quickstart

End-to-end first-incident setup for cloud or local-only DebugBundle projects, including verification and bundle inspection.

Use Cloud when you are preparing a hosted deployment or already running in production. Events go to DebugBundle Cloud, where you can inspect incidents with your team, receive alerts, send webhooks, run GitHub automations, and keep a local fallback for development.

Agent Path

Copy this prompt into your coding agent:

Set up DebugBundle for this repository end to end.
Inspect the project language, framework, package manager, entry points, logging setup, and whether it has a frontend, browser surface, or server-rendered UI.
Read the relevant DebugBundle docs: https://debugbundle.com/docs/installation, https://debugbundle.com/docs/quickstart, https://debugbundle.com/docs/project-setup/connect-to-cloud, https://debugbundle.com/docs/cli/cloud-workflow, https://debugbundle.com/docs/cli/local-workflow, https://debugbundle.com/docs/sdks, https://debugbundle.com/docs/integrations/wordpress, and https://debugbundle.com/docs/agent-workflows/skill-file.
Run `debugbundle setup`, then read and follow `.agents/skills/debugbundle/SKILL.md`.
Choose Cloud mode for hosted deployment or shared incident workflows; otherwise use local-only mode.
If Cloud is appropriate, run `debugbundle login` and `debugbundle connect`.
Install the smallest safe integration path: backend SDK, WordPress plugin, or log ingestion.
If the repository or deployment target is WordPress, use the DebugBundle WordPress plugin instead of installing the PHP SDK or Browser SDK directly on the WordPress host; still keep the `debugbundle setup` scaffold in the repo, but let the plugin own backend capture, browser capture, relay setup, and token storage.
For browser-capturable UI, also install the Browser SDK and configure same-origin relay for full-stack apps or direct capture for frontend-only apps.
Configure required env vars or tokens.
Trigger one intentional test error through the real ingestion path.
Verify with `debugbundle verify cloud` or `debugbundle verify local`, then show the incident using `debugbundle incidents --source cloud|local` and inspect it with `debugbundle inspect <incident-id>`.

The agent should end with a connected cloud project, a verified hosted incident, and a bundle visible from debugbundle inspect <incident-id>.

Manual Path

1. Install the CLI

npm install -g @debugbundle/cli
debugbundle --version

The CLI drives setup, authentication, cloud connection, verification, and incident inspection. If you do not want to install the CLI globally, run it through your normal Node package runner for local tooling.

2. Scaffold the Project

debugbundle setup

This creates .debugbundle/profile.json, .debugbundle/local/connection.json, local event directories, and the agent skill files. Keep profile.json and connection.json in git. Keep .debugbundle/local/ and .debugbundle/bundles/ ignored.

3. Connect to Cloud

debugbundle login
debugbundle connect

connect creates or selects a cloud project, creates a write-only project token, and updates .debugbundle/local/connection.json. Store the shown project token in your hosted environment:

DEBUGBUNDLE_PROJECT_TOKEN=dbundle_proj_xxxxxxxxxxxx

4. Add Capture

Pick the path that matches your project.

If you need frontend exceptions, breadcrumbs, and browser-to-backend trace correlation, add the Browser SDK too. Use it by itself for frontend-only cloud deployments, or pair it with a backend relay for full-stack apps.

npm install @debugbundle/sdk-node

import DebugBundle from '@debugbundle/sdk-node';

DebugBundle.init({
  projectToken: process.env.DEBUGBUNDLE_PROJECT_TOKEN,
  environment: 'production',
  service: 'api',
});

DebugBundle.captureExceptions();
DebugBundle.captureRejections();

For framework middleware, logger capture, and browser relay setup, see Node.js SDK.

npm install @debugbundle/sdk-browser

import DebugBundle from '@debugbundle/sdk-browser';

DebugBundle.init({
  projectToken: '<public-project-token>',
  environment: 'production',
  service: 'web',
});

For frontend-only apps, the Browser SDK can send directly to DebugBundle Cloud with a public write-only project token; create a dedicated token with --allowed-origin https://your-site.example for browser abuse reduction. For full-stack apps, prefer a backend relay and omit projectToken on the client. Same-origin relay paths such as /debugbundle/browser are simplest; split frontend/backend apps can use explicit relay mode with an absolute backend relay URL. See Browser SDK and Browser Relay Setup.

pip install debugbundle-python

import os
import debugbundle

debugbundle.init(
    project_token=os.environ["DEBUGBUNDLE_PROJECT_TOKEN"],
    environment="production",
    service="api",
)

debugbundle.capture_exceptions()
debugbundle.capture_logging()

For Django, Flask, FastAPI, structlog, and loguru, see Python SDK.

composer require debugbundle/sdk-php

<?php

use DebugBundle\DebugBundle;

DebugBundle::init([
    'projectToken' => getenv('DEBUGBUNDLE_PROJECT_TOKEN'),
    'environment' => 'production',
    'service' => 'api',
]);

DebugBundle::captureErrors();
DebugBundle::captureExceptions();
DebugBundle::captureShutdown();

For Laravel, Symfony, and Monolog, see PHP SDK.

<dependency>
  <groupId>com.debugbundle</groupId>
  <artifactId>debugbundle-spring-boot-starter</artifactId>
  <version>1.1.1</version>
</dependency>

debugbundle:
  project-token: ${DEBUGBUNDLE_PROJECT_TOKEN}
  environment: production
  service: api
  project-mode: connected

Use this path for Spring Boot 3.x. For servlet WARs, JAX-RS services, WildFly, or JBoss deployments, use the broader Java SDK setup.

Spring Boot 3.x applications auto-configure servlet request capture, MVC exception capture, Logback capture, remote capture policy, probes, and the optional browser relay.

dotnet add package DebugBundle.AspNetCore
dotnet add package DebugBundle.Extensions.Logging

builder.Services.AddDebugBundle(options =>
{
    options.ProjectToken = builder.Configuration["DEBUGBUNDLE_PROJECT_TOKEN"];
    options.Environment = builder.Environment.EnvironmentName;
    options.Service = "api";
});
builder.Logging.AddDebugBundle();

var app = builder.Build();
app.UseDebugBundle();
app.MapDebugBundleBrowserRelay("/debugbundle/browser");

For ASP.NET Core, gRPC, Worker Service, Hangfire, Azure Functions isolated worker, logging adapters, probes, and browser relay setup, see .NET SDK.

go get github.com/debugbundle/debugbundle-go

client := debugbundle.New(debugbundle.Config{
	ProjectToken: os.Getenv("DEBUGBUNDLE_PROJECT_TOKEN"),
	Environment:  "production",
	Service:      "api",
})
defer func() { _ = client.Flush(context.Background()) }()

For net/http, Gin, Echo, logging integrations, probes, and browser relay setup, see Go SDK.

bundle add debugbundle

require "debugbundle"

DebugBundle.init(
  project_token: ENV["DEBUGBUNDLE_PROJECT_TOKEN"],
  environment: "production",
  service: "api",
  project_mode: :connected
)

For Rails, Rack, Sidekiq, logging integrations, probes, and browser relay setup, see Ruby SDK.

dependencies {
    implementation(platform("com.debugbundle:debugbundle-android-bom:0.1.2"))
    implementation("com.debugbundle:debugbundle-android")
    implementation("com.debugbundle:debugbundle-android-okhttp")
}

DebugBundle.init(
    application = this,
    config = DebugBundleConfig(
        projectToken = BuildConfig.DEBUGBUNDLE_PROJECT_TOKEN,
        environment = "production",
        service = "android-app",
    ),
)

For Android crash replay, ANR/process-exit capture, offline queueing, OkHttp, Ktor client, Navigation, Compose, Timber, and probes, see Android SDK.

.package(
    url: "https://github.com/debugbundle/debugbundle-swift",
    from: "0.1.1"
)

DebugBundle.initialize(
    DebugBundleConfig(
        projectToken: Bundle.main.debugBundleProjectToken,
        environment: "production",
        service: "ios-app"
    )
)

For SwiftUI/UIKit lifecycle breadcrumbs, URLSession, Alamofire, SwiftLog, crash replay, offline queueing, and probes, see iOS SDK.

npm install @debugbundle/sdk-react-native
cd ios && pod install

import { DebugBundle } from '@debugbundle/sdk-react-native';

DebugBundle.init({
  projectToken: process.env.EXPO_PUBLIC_DEBUGBUNDLE_TOKEN,
  environment: __DEV__ ? 'development' : 'production',
  service: 'mobile-app',
  tracePropagationTargets: ['https://api.example.com'],
});

For React error-boundary capture, React Navigation breadcrumbs, fetch/XHR trace propagation, Expo development builds, native offline queueing, and Expo Go caveats, see React Native SDK.

Use log ingestion when you cannot add an SDK yet.

debugbundle watch --cloud --log ./storage/logs/app.log --format php-error
debugbundle watch --cloud --log ./var/log/apache/error.log --format apache-error

For structured input, emit DebugBundle NDJSON and ingest it:

debugbundle watch --cloud --log ./debugbundle.ndjson --format debugbundle-ndjson

See Log Ingestion.

5. Verify Cloud Ingestion

Deploy or run the configured service with DEBUGBUNDLE_PROJECT_TOKEN set, then verify ingestion:

debugbundle verify cloud --project-id proj_01HXYZ... --trigger-5xx
debugbundle incidents --source cloud
debugbundle inspect inc_01HXYZ...

verify cloud --trigger-5xx sends a synthetic request-failure event through hosted ingestion, polls for the incident and bundle, and reports whether the cloud path is ready.

If you want to prove your real SDK wiring instead, trigger a known app-side event and run debugbundle verify cloud --project-id proj_01HXYZ... --expect-app-event --service api-server --trace-id trace_123 so the CLI waits for the hosted incident and matches the resulting bundle with your correlation hint.

What You Should See

A cloud incident includes the same bundle context as local mode, plus hosted workflows:

Capability	Purpose
Hosted incidents	Team-visible incident list, status, assignment, and bundle access
Alerts	Email, Slack, Discord, or webhook notifications for lifecycle events
Webhooks	Signed automation events for incident and verification workflows
GitHub automation	Repository dispatch and follow-up workflows owned by your repo
MCP/API access	Agent and automation access to incidents, bundles, probes, and project operations

Next Steps

Connect to Cloud — Understand project tokens and delivery modes
CLI Cloud Workflow — Verify, inspect, resolve, and manage cloud incidents

Use local-only when you want DebugBundle to process incidents on the machine where captured files live without a hosted account. That can be your development machine or a self-managed server with persistent storage and CLI access. Browser capture still needs a backend relay so the browser SDK can hand events to your backend for local processing.

Agent Path

Copy this prompt into your coding agent:

Set up DebugBundle for this repository in local-only mode.
Inspect the project language, framework, package manager, entry points, logging setup, and whether it has a frontend, browser surface, or server-rendered UI.
Read the relevant DebugBundle docs: https://debugbundle.com/docs/installation, https://debugbundle.com/docs/quickstart, https://debugbundle.com/docs/cli/local-workflow, https://debugbundle.com/docs/sdks, https://debugbundle.com/docs/integrations/wordpress, and https://debugbundle.com/docs/agent-workflows/skill-file.
Run `debugbundle setup`, then read and follow `.agents/skills/debugbundle/SKILL.md`.
Do not use DebugBundle Cloud for this setup. Keep the project in local-only mode and process incidents on this machine.
Install the smallest safe integration path: backend SDK, WordPress plugin, or log ingestion.
If the repository or deployment target is WordPress, use the DebugBundle WordPress plugin instead of installing the PHP SDK or Browser SDK directly on the WordPress host; still keep the `debugbundle setup` scaffold in the repo, but let the plugin own backend capture, browser capture, relay setup, and token storage.
For browser-capturable UI, also install the Browser SDK and configure a backend same-origin relay because local-only browser capture still needs a relay target.
Configure the local-only settings and any required local environment values.
Trigger one intentional test error through the real local ingestion path.
Run `debugbundle process`, then verify with `debugbundle verify local`, show the incident using `debugbundle incidents --source local`, and inspect it with `debugbundle inspect <incident-id>`.

The agent should end with a processed local incident and a bundle visible from debugbundle inspect.

Manual Path

1. Install the CLI

npm install -g @debugbundle/cli
debugbundle --version

The CLI drives setup, local processing, inspection, and optional cloud connection. If you do not want to install the CLI globally, run it through your normal Node package runner for local tooling.

2. Scaffold the Project

debugbundle setup

3. Add Capture

Pick the path that matches your project.

Local-only browser capture requires a backend relay so the browser SDK can hand events to your backend, which then writes them into .debugbundle/local/events/ for debugbundle process.

npm install @debugbundle/sdk-node

import DebugBundle from '@debugbundle/sdk-node';

DebugBundle.init({
  projectToken: 'local',
  environment: 'development',
  service: 'api',
});

DebugBundle.captureExceptions();
DebugBundle.captureRejections();

For framework middleware and logger capture, see Node.js SDK.

npm install @debugbundle/sdk-browser

import DebugBundle from '@debugbundle/sdk-browser';

DebugBundle.init({
  transportMode: 'relay',
  endpoint: '/debugbundle/browser',
  environment: 'development',
  service: 'web',
});

Use the Browser SDK with a relay mounted on your backend in local-only mode. If your app has no backend, use the cloud quickstart instead because local-only browser capture needs a relay target. See Browser SDK and Browser Relay Setup.

pip install debugbundle-python

import debugbundle

debugbundle.init(
    project_token="local",
    environment="development",
    service="api",
)

debugbundle.capture_exceptions()
debugbundle.capture_logging()

For Django, Flask, FastAPI, structlog, and loguru, see Python SDK.

composer require debugbundle/sdk-php

<?php

use DebugBundle\DebugBundle;

DebugBundle::init([
    'projectToken' => 'local',
    'environment' => 'development',
    'service' => 'api',
]);

DebugBundle::captureErrors();
DebugBundle::captureExceptions();
DebugBundle::captureShutdown();

For Laravel, Symfony, and Monolog, see PHP SDK.

<dependency>
  <groupId>com.debugbundle</groupId>
  <artifactId>debugbundle-spring-boot-starter</artifactId>
  <version>1.1.1</version>
</dependency>

debugbundle:
  project-token: local
  environment: development
  service: api
  project-mode: local-only

Use this path for Spring Boot 3.x. For servlet WARs, JAX-RS services, WildFly, or JBoss deployments, use the broader Java SDK setup.

Spring Boot 3.x applications auto-configure servlet request capture, MVC exception capture, Logback capture, probes, and local file delivery.

dotnet add package DebugBundle.AspNetCore
dotnet add package DebugBundle.Extensions.Logging

builder.Services.AddDebugBundle(options =>
{
    options.ProjectMode = DebugBundleProjectMode.LocalOnly;
    options.LocalEventsDir = ".debugbundle/local/events";
    options.Environment = "development";
    options.Service = "api";
});
builder.Logging.AddDebugBundle();

var app = builder.Build();
app.UseDebugBundle();
app.MapDebugBundleBrowserRelay("/debugbundle/browser");

.NET local-only mode writes ASP.NET Core request, exception, log, probe, and browser relay events into .debugbundle/local/events/ for debugbundle process. See .NET SDK.

go get github.com/debugbundle/debugbundle-go

client := debugbundle.New(debugbundle.Config{
	ProjectToken:   "local",
	Environment:    "development",
	Service:        "api",
	ProjectMode:    debugbundle.ProjectModeLocalOnly,
	LocalEventsDir: ".debugbundle/local/events",
})
defer func() { _ = client.Flush(context.Background()) }()

For net/http, Gin, Echo, logging integrations, probes, and browser relay setup, see Go SDK.

bundle add debugbundle

require "debugbundle"

DebugBundle.init(
  project_token: "local",
  environment: "development",
  service: "api",
  project_mode: :local_only
)

For Rails, Rack, Sidekiq, logging integrations, probes, and browser relay setup, see Ruby SDK.

dependencies {
    implementation(platform("com.debugbundle:debugbundle-android-bom:0.1.2"))
    implementation("com.debugbundle:debugbundle-android")
    implementation("com.debugbundle:debugbundle-android-okhttp")
}

DebugBundle.init(
    application = this,
    config = DebugBundleConfig(
        projectToken = "local",
        environment = "development",
        service = "android-app",
    ),
)

The Android SDK writes through its app-private offline queue in local/development paths and can flush through the normal ingestion endpoint when connected. For runtime setup and local limitations, see Android SDK.

.package(
    url: "https://github.com/debugbundle/debugbundle-swift",
    from: "0.1.1"
)

DebugBundle.initialize(
    DebugBundleConfig(
        projectToken: "local",
        environment: "development",
        service: "ios-app",
        endpoint: URL(string: "http://127.0.0.1:9001/v1/events")!
    )
)

The iOS SDK writes through its app-private offline queue in local/development paths and can flush through a mock, staging, or self-hosted ingestion endpoint reachable from the simulator or device. Use the simulator loopback host, LAN IP, or self-hosted URL that your target device can actually reach. For runtime setup and local limitations, see iOS SDK.

npm install @debugbundle/sdk-react-native
cd ios && pod install

import { DebugBundle } from '@debugbundle/sdk-react-native';

DebugBundle.init({
  projectToken: 'local',
  environment: 'development',
  service: 'mobile-app',
  endpoint: 'http://127.0.0.1:9001/v1/events',
  tracePropagationTargets: ['http://127.0.0.1:3000'],
});

React Native writes through the native Android/iOS offline queues and can flush to a mock, staging, self-hosted, or cloud endpoint reachable from the simulator or device. It does not write .debugbundle/local/events directly. For runtime setup and local limitations, see React Native SDK.

Use log ingestion when you cannot add an SDK yet.

debugbundle ingest ./storage/logs/app.log --format php-error
debugbundle ingest ./var/log/apache/error.log --format apache-error

For structured input, emit DebugBundle NDJSON and ingest it:

debugbundle ingest ./debugbundle.ndjson --format debugbundle-ndjson

See Log Ingestion.

4. Trigger One Test Event

Trigger an intentional error in your local app, or capture a handled exception from code:

try {
  await riskyOperation();
} catch (error) {
  DebugBundle.captureException(error);
}

For Python, PHP, Java, .NET, Go, Ruby, Android, iOS, or React Native, use the equivalent language-specific capture method from the SDK guide.

5. Process and Inspect

debugbundle process
debugbundle inspect

process normalizes raw events, groups them into local incidents, and writes bundle artifacts. inspect prints the latest incident bundle in the terminal.

What You Should See

A local bundle includes:

Block	Purpose
`summary`	Title, severity, service, environment, first seen, occurrence count
`context.error`	Error class, message, stack trace, and normalized frames
`context.request`	Request method, path, route, headers, body summary when available
`context.runtime`	Language, runtime version, OS, and architecture
`context.git`	Commit, branch, and dirty-state metadata when detectable
`reproduction`	cURL, HTTPie, or JSON replay artifacts when request context is available

Next Steps

Installation — Choose the right install path for each SDK and runtime
CLI Local Workflow — Process, inspect, resolve, reopen, and clean up incidents
SDKs — Language-specific setup and capture options
Core Concepts — Bundles, incidents, profiles, and event types

Optional Agent-Assisted Improvements

These are not required for your first DebugBundle incident. Use them once capture is working and you want an agent to improve signal quality or live-debugging coverage.

Alert on critical paths

Use an agent to identify the routes, jobs, and integrations where DebugBundle alerts should stay high-signal and business-relevant.

Hosted health checks

Use an agent to choose the safest public endpoints to monitor and wire availability failures into the normal incident workflow.

Remote probes on demand

Use an agent to identify a small set of high-leverage probe points that improve live debugging without adding noisy permanent instrumentation.

Quickstart

Optional Agent-Assisted Improvements

Alert on critical paths

Hosted health checks

Remote probes on demand

On this page