Setup & Configuration

Quick Setup

Run setup from your project root:

debugbundle setup

For CI or agent-driven environments:

debugbundle setup --non-interactive --json

The setup command:

1. Detects your project name, services, frameworks, and runtimes from manifests, lockfiles, and source files
2. Generates the local scaffold (profile, connection config, agent skill, references)
3. Updates .gitignore to exclude local runtime data
4. Scaffolds a relay route when a supported backend framework is detected

The generated skill teaches agents the incident-first workflow, profile validation, browser relay verification, incident resolution hygiene, and when to evaluate repeated low-value incidents for capture-rule suggestions or path-scoped client-error capture policy.

For split frontend/backend repositories, use the canonical Split Frontend & Backend guide after setup. It covers relay ownership, backend-only token placement, cross-origin browser endpoint configuration, container workflow, and production deployment notes.

The .debugbundle/ Directory

After setup, your project contains:

Git tracking:

• .debugbundle/profile.json and .debugbundle/local/connection.json are tracked (committed)
• .debugbundle/local/* (events, spool), .debugbundle/bundles/ are gitignored
• .agents/skills/debugbundle/ is tracked — agents read these references at session start

Profile

The profile (profile.json) is a full repository profile, not just a service list. It covers project identity, services, infrastructure, critical paths, repository layout, developer workflows, and DebugBundle review metadata:

{
  "profile_version": "v1",
  "project": {
    "name": "my-api",
    "repo_url": "https://github.com/org/my-api",
    "primary_languages": ["TypeScript"],
    "package_managers": ["pnpm"],
    "deployment_targets": ["docker-compose"]
  },
  "services": [
    {
      "name": "api",
      "kind": "backend",
      "runtime": "Node.js",
      "framework": "Express",
      "paths": ["apps/api"],
      "owns_routes": ["POST /checkout"],
      "depends_on": ["postgres", "redis"]
    },
    {
      "name": "worker",
      "kind": "worker",
      "runtime": "Node.js",
      "framework": "none",
      "paths": ["apps/worker"],
      "owns_routes": [],
      "depends_on": ["redis"]
    }
  ],
  "infrastructure": {
    "databases": ["postgres"],
    "queues": ["redis"],
    "object_storage": [],
    "external_services": []
  },
  "critical_paths": [
    {
      "name": "checkout",
      "owner_service": "api",
      "notes": "Creates the order and enqueues fulfillment."
    }
  ],
  "repo": {
    "root_paths": ["apps", "packages"],
    "generated_paths": ["dist"],
    "do_not_edit_paths": []
  },
  "developer_workflows": {
    "install": "pnpm install",
    "build": "pnpm build",
    "test": "pnpm test",
    "lint": "pnpm lint"
  },
  "debugbundle": {
    "profile_owner": "team-debugging",
    "last_reviewed_at": "2025-01-15T00:00:00.000Z",
    "validation_status": "static-analysis-only",
    "skill_path": ".agents/skills/debugbundle/SKILL.md",
    "notes": "Review after setup and update when architecture changes."
  }
}

Setup generates the profile from static analysis. You should review and correct it:

1. Verify service names, kinds, runtimes, and frameworks
2. Add missing critical paths or ownership details
3. Validate with debugbundle profile validate
4. Update validation_status to agent-validated when the profile is accurate

Connection Config

The connection file (.debugbundle/local/connection.json) controls transport behavior:

{
  "mode": "local-only"
}

Doctor

Run diagnostic checks on your DebugBundle installation:

debugbundle doctor

Output:

DebugBundle doctor report.
Status: healthy
Checks:
- profile: ok - .debugbundle/profile.json exists and is valid.
- connection: ok - .debugbundle/local/connection.json exists and is valid.
- skill: ok - .agents/skills/debugbundle/SKILL.md exists.
- auth: ok - ~/.debugbundle/auth.json exists and contains a valid token.

Checks Performed

Relay Check

Check the browser relay health:

debugbundle doctor --check-relay

This reports undelivered relay spool files and their age.

Java Deployment Checks

For Java projects, setup and doctor distinguish the supported deployment shapes instead of treating every backend as Spring Boot:

The Javaagent currently bootstraps core SDK, uncaught exception, and JUL/JBoss LogManager-compatible logging hooks. Request and browser-relay capture are verified through the Spring starter or WAR-level servlet/JAX-RS adapters.

JSON Output

debugbundle doctor --json

Returns structured JSON with status, checks, warnings, errors, and suggested_actions.

debugbundle setup --json also exposes detected_services, selected_targets, relay_action, and relay_guidance so CI and agent workflows can see which surfaces were prepared and whether relay setup was scaffolded or left as runtime-specific instructions.

For connected projects, debugbundle doctor also validates the configured cloud or self-host API base URL. It checks GET /health, then verifies member-token auth against a lightweight retrieval request so misconfigured self-host endpoints fail early.

Validate

Verify scaffold files exist and are structurally correct:

debugbundle validate

Validation also compares the generated skill, reference files, analysis schemas, and evals against the current CLI templates. Stale managed guidance returns a warning so teams notice when their committed agent workflow has drifted.

Auto-Fix Mode

Regenerate missing or stale scaffold files without overwriting your profile:

debugbundle validate --fix

This recreates or refreshes reference files, skill definitions, schemas, evals, and directory structures while preserving your manually-reviewed profile.json.

Verify

Local Verification

Confirm the local scaffold is healthy and events can be processed:

debugbundle verify local

Cloud Verification

Confirm cloud ingestion is working for a specific project:

debugbundle verify cloud \
  --project-id proj_xxxx \
  --service api \
  --environment production \
  --max-age-minutes 60

This checks that events from the specified service and environment have been received within the lookback window.

To actively prove the hosted incident pipeline, use one of the trigger modes:

# Synthetic 5xx request failure
debugbundle verify cloud --project-id proj_xxxx --trigger-5xx

# Synthetic configured client-error incident
debugbundle verify cloud --project-id proj_xxxx --trigger-4xx 403

The 4xx trigger succeeds only when the project capture policy promotes that status.

Next Steps

• Split Frontend & Backend — Canonical setup path for separate browser and API services
• Local Workflow — Processing events and inspecting incidents
• CLI Overview — Full command index and authentication