Connect to Cloud

The debugbundle connect command links your local project to DebugBundle Cloud, enabling team-wide incident visibility, webhooks, alerts, probes, and the web dashboard.

Prerequisites

• A DebugBundle account (sign up at app.debugbundle.com)
• CLI authenticated: debugbundle login
• An initialized local project: debugbundle setup

If you are not authenticated yet, debugbundle connect can now prompt you to log in first and then continue automatically.

Choose the system's project

Prefer one project per system, with Site, App, API and Worker as services across repositories. Keep separate projects when access or privacy policies require separation. Preserve an existing connection, credentials and existing SDK input names.

For an unconnected repository, inspect debugbundle project list --json first. connect matches the slugified profile name; it does not infer system membership and has no project-selection flag. To reuse a known project with a different name, set mode to connected, its exact cloud_project_id and API origin using the configuration below, preserving unrelated settings. Supply a write-only token for that same project through the runtime's secret configuration; create a dedicated token only if needed with debugbundle token project create PROJECT_ID --label SERVICE. Browser direct capture requires a dedicated public token with allowed origins; never expose a server token. See Tokens.

If no suitable project exists, choose the system's name in profile.json before running connect. Existing separate projects require an explicitly approved consolidation.

Connect Flow

debugbundle connect

The connect command performs these steps automatically:

1. Reads your profile — extracts the project name from .debugbundle/profile.json
2. Prompts for login if needed — offers GitHub auto mode, GitHub device flow, or an existing member token when local auth is missing
3. Creates or selects a cloud project — matches the slugified profile name against existing project slugs, creating a project if there is no match
4. Generates a project token — creates a write-only SDK token for event ingestion
5. Updates connection.json — switches mode to "connected" and enables cloud delivery for the production environment

Output

Connected DebugBundle project to cloud.
Created cloud project: my-app (proj_01HXYZ...)
Updated .debugbundle/local/connection.json with production cloud delivery defaults.
Local investigation artifacts remain available under .debugbundle/local/.
Project token:
dbundle_proj_a1b2c3d4...
Next steps:
- Set DEBUGBUNDLE_PROJECT_TOKEN=dbundle_proj_a1b2c3d4... in your production environment.
- Redeploy connected environments after updating their DebugBundle configuration.
- Use debugbundle incidents --source cloud after deployment to confirm hosted ingestion.

Connection Configuration

After connecting, your .debugbundle/local/connection.json looks like:

{
  "mode": "connected",
  "cloud_project_id": "proj_01HXYZ...",
  "cloud_base_url": "https://api.debugbundle.com",
  "environments": {
    "local": { "delivery": "local-only" },
    "development": { "delivery": "local-only" },
    "staging": { "delivery": "local-only" },
    "production": { "delivery": "cloud-enabled" }
  }
}

Configuration Fields

Environment Delivery

Each environment independently controls whether events are delivered locally or to the cloud:

Default after connect:

• local, development, and staging → local-only (keep pre-production investigation local by default)
• production → cloud-enabled (team visibility where it matters)

You can change any environment's delivery mode by editing connection.json.

Verify Cloud Connection

After deploying with the project token, verify the connection:

debugbundle verify cloud --project-id proj_01HXYZ...

This checks:

• API is reachable
• Your member token is valid
• The cloud project exists and is accessible
• Recent events have been received within the verification window

To actively prove hosted incident creation, send a synthetic request event through the real ingestion path:

# Prove the standard request-failure path
debugbundle verify cloud --project-id proj_01HXYZ... --trigger-5xx

# Prove a configured client-error incident path
debugbundle verify cloud --project-id proj_01HXYZ... --trigger-4xx 403

The 4xx proof succeeds only when the target project's capture policy promotes that status, for example with immediate_client_error_statuses containing 403.

To prove your real app-side SDK wiring instead of the synthetic path, trigger a known browser or backend SDK event and let the CLI wait for hosted visibility:

debugbundle verify cloud \
  --project-id proj_01HXYZ... \
  --expect-app-event \
  --service checkout-api \
  --environment production \
  --trace-id trace_123 \
  --request-id req_456

Use --trace-id or --request-id when you have a correlation hint from the app or browser network trace. That keeps the verification scoped to the event you intentionally triggered instead of any unrelated recent incident.

JSON Output

debugbundle verify cloud --project-id proj_01HXYZ... --json

{
  "status": "healthy",
  "checks": [
    { "name": "api_reachable", "status": "ok", "message": "API responded in 42ms" },
    { "name": "auth_valid", "status": "ok", "message": "Member token is valid" },
    { "name": "project_accessible", "status": "ok", "message": "Project proj_01HXYZ... is accessible" },
    { "name": "recent_events", "status": "ok", "message": "Last event received 3 minutes ago" }
  ],
  "warnings": [],
  "errors": [],
  "suggested_actions": [],
  "auto_fix_available": false
}

Merged Incident View

After connecting, you can view both local and cloud incidents together:

# Active incidents (both sources)
debugbundle incidents

# Cloud only
debugbundle incidents --source cloud

# Local only
debugbundle incidents --source local

Security

• Project tokens are write-only — they can only ingest events, not read data.
• Member tokens are used for CLI/API/MCP operations (read + manage).
• Tokens are hashed (SHA-256) before storage. Plaintext is shown once at creation.
• Cloud delivery uses HTTPS with TLS 1.2+.

Next Steps

• Project Setup — Setup overview
• Local-Only Mode — Return to local-only mode
• Capture Policy — Control event capture behavior
• CLI Cloud Workflow — Full cloud CLI workflow