Installation catalog

Component-by-component install reference for DebugBundle after you have already chosen a setup path.

Starting from zero? Use Quickstart first. This page is a component catalog for teams that already know whether they are setting up cloud, local-only, browser relay, or self-hosting.

Install the CLI first, then add the SDK or ingestion path that matches your runtime.

Need your first working incident, bundle, and verification flow? Follow Quickstart instead. Come back here once you already know which runtime or component you need to install manually.

CLI

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

The CLI runs setup, local processing, incident inspection, token management, cloud connection, and verification.

Installing the CLI is not the same as setting up a project. For first-time setup, run debugbundle setup and continue with the manual path in Quickstart.

SDKs

npm install @debugbundle/sdk-node

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

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

Framework exports include Express, Fastify, Next.js, and browser relay handlers. See Node.js SDK.

npm install @debugbundle/sdk-browser

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

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

Browser events should usually go through a backend relay. A same-origin path is 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 debugbundle

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

Django, Flask, FastAPI, structlog, and loguru integrations are included. See Python SDK.

composer require debugbundle/sdk-php

<?php

use DebugBundle\DebugBundle;

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

Laravel, Symfony, and Monolog integrations are included. 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 get servlet request capture, MVC exception capture, Logback capture, remote config, probes, and an optional same-origin 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");

ASP.NET Core, Microsoft.Extensions.Logging, gRPC, Worker Service, Hangfire, Azure Functions isolated worker, Serilog, NLog, log4net, and browser relay packages are published on NuGet. 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()) }()

net/http, Gin, Echo, slog, zap, zerolog, local file transport, remote capture policy, probes, and browser relay handlers are included. See Go SDK.

gem "debugbundle"

require "debugbundle"

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

Rails, Rack, Sidekiq, Ruby Logger, Semantic Logger, local file transport, remote capture policy, probes, and browser relay handlers are included. 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",
    ),
)

The Android SDK covers native runtime capture, crash/ANR replay, WorkManager flushing, 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"
    )
)

The iOS SDK covers native iOS/iPadOS runtime capture, crash replay helpers, offline queueing, URLSession, Alamofire, UIKit, SwiftUI, SwiftLog, 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'],
});

React Native supports iOS and Android through a TypeScript facade, React error boundary, React Navigation breadcrumbs, scoped fetch/XHR trace propagation, Expo development builds, and native queueing foundations. Minimum compatibility is React Native 0.76+, with current-stable 0.85.x recommended for production. See React Native SDK.

Install DebugBundle from the WordPress.org plugin directory in Plugins -> Add New, then activate it. Manual ZIP installs are available from the debugbundle-wordpress GitHub releases page when a host or deployment process cannot install from WordPress.org.

After activation, open Settings -> DebugBundle, paste your project token, and save. The plugin bundles the PHP and browser SDKs, creates the same-origin browser relay, and keeps the project token server-side.

See WordPress Plugin.

Browser Relay

Browser SDKs should not hold project tokens. Add a relay on your backend, then point the browser SDK at that route.

Runtime	Import
Generic Node.js	`@debugbundle/sdk-node/relay`
Express	`@debugbundle/sdk-node/relay/express`
Fastify	`@debugbundle/sdk-node/relay/fastify`
Next.js API route	`@debugbundle/sdk-node/relay/nextjs`
ASP.NET Core	`app.MapDebugBundleBrowserRelay("/debugbundle/browser")`

See Browser Relay Setup.

WordPress sites do not need a custom relay route. Use the WordPress Plugin, which registers /wp-json/debugbundle/v1/browser automatically.

Log Ingestion

Use log ingestion when SDK installation is not possible yet.

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

Supported first-party parser formats include debugbundle-ndjson, php-error, and apache-error. See Log Ingestion.

MCP

Use the MCP package when an AI agent or MCP-compatible client needs DebugBundle incident and bundle tools.

npx @debugbundle/mcp

The official MCP Registry name is com.debugbundle/mcp. Local clients can reuse CLI auth state from ~/.debugbundle/auth.json; headless or marketplace-managed clients should set DEBUGBUNDLE_MEMBER_TOKEN in the MCP server environment. Project tokens are SDK write-only ingestion credentials and must not be used for MCP retrieval or management.

See MCP Server, MCP Distribution, and MCP Tools Reference.

Self-Hosting

git clone https://github.com/debugbundle/debugbundle.git
cd debugbundle/deploy/selfhost
cp .env.example .env
docker compose up -d

The self-host stack includes the web app, API, worker, PostgreSQL, Redis, and LocalStack S3. See Self-Hosting for environment variables, health checks, backups, and updates.

Next Steps

Quickstart — Capture and inspect your first local bundle
Project Setup — Understand .debugbundle/ and profile.json
CLI Setup — Setup, doctor, validate, and verify commands
SDKs — Full language-specific setup guides