Debug Manager

Manage Debug settings and create bounded diagnostic support bundles.

nimbus debug <command>

Command	Description
`list`	Show current Debug settings
`export <path>`	Export Debug settings to a JSON file
`import <path>`	Import Debug settings from a JSON file
`download-bundle <path>`	Create a Debug support bundle ZIP, with local offline collection when Agent is stopped
`upload-bundle [--path <path>]`	Create a Debug support bundle ZIP and upload it to the configured cloud storage

Support-bundle selection options:

--from <time>: UTC lower bound in ISO-8601 or a relative value like "1 hour ago". Empty uses the agent default window.
--to <time>: UTC upper bound in ISO-8601, now, or a relative value like "5 minutes ago". Empty uses now.
--domains <ids>: comma-separated domain ids. Empty includes all support-bundle domains.
--limit <n>: structured diagnostic rows per domain. Zero uses the agent default.
--service-log-line-limit <n>: raw service-log lines. Zero uses the agent default.
--max-mb <n>: maximum bundle size in MB. Zero uses the agent default.

Supported support-bundle domains:

agent-structured-logs
agent-service-log
frontend-telemetry
memory-diagnostics
sidecar-diagnostics
agent-lifecycle
agent-db-health
video-diagnostics
resources-storage-diagnostics
stream-upload-diagnostics
metric-upload-diagnostics
installer-logs
tasks

If the local Agent connection is refused, download-bundle collects retained evidence on the CLI machine without starting Agent or Sidecar. It includes readable installation logs, the Agent service journal, Sidecar/updater evidence, and partial host lifecycle information. Runtime-only domains are marked unavailable in manifest.json. Private journals and installer logs may require running the command with sudo.

Offline export keeps the same selection options and reports the applied limits; its service-journal cap is lower than the full Agent export. Authentication errors, export failures, remote target failures, and ambiguous timeouts do not trigger local collection. upload-bundle requires Agent and cloud access.

With Sidecar running, open http://127.0.0.1:19995/debug in a browser on the robot and use Download offline support bundle. The form supports UTC window, domain, and size/line selection and uses the same offline exporter as CLI. Sidecar diagnostics listen on loopback only.

Installation results describe local installation and cloud status reporting separately. A successful installation result does not establish that Agent stayed running or completed cloud login; the same bundle carries the service journal for that diagnosis. Limited installer output retains the beginning and newest tail, including final result markers when the budget permits.

tasks exports run summaries and retained execution details for runs overlapping the requested window, including navigation observations and script stdout/stderr. Detailed observations are filtered to that window. The Agent scans at most the newest 200 run summaries and retains at most 2 MiB of task payload, also subject to the selected row limit and remaining bundle/domain budget. The export marks omitted details and incomplete source coverage explicitly; older runs can lack execution details.

Autocomplete and inline help are driven by the DebugManagerService command registration and the support-bundle request parsers. Domain ids are free-form option values, so keep the documented domain list aligned with DebugSupportBundleService when adding new bundle domains.

Examples

# Show current Debug settings
nimbus debug list

# Export/import Debug settings
nimbus debug export /tmp/debug-settings.json
nimbus debug import /tmp/debug-settings.json

# Download a bundle with all domains using agent defaults
nimbus debug download-bundle /tmp/nimbus-debug-bundle.zip

# Collect available evidence after local Agent startup fails; no service restart is needed
sudo nimbus debug download-bundle /tmp/nimbus-startup-failure.zip

# Download a bundle for the last hour
nimbus debug download-bundle /tmp/nimbus-debug-last-hour.zip --from "1 hour ago"

# Download task execution evidence for the last hour
nimbus debug download-bundle /tmp/nimbus-task-debug.zip --from "1 hour ago" --domains tasks

# Download only frontend telemetry for a specific UTC window
nimbus debug download-bundle /tmp/frontend-debug.zip \
  --from 2026-06-16T08:00:00Z \
  --to 2026-06-16T09:00:00Z \
  --domains frontend-telemetry

# Download the largest bundle currently allowed for the default diagnostics window.
# Retention, enabled diagnostics, per-domain byte caps, row caps, and the hard bundle cap still apply.
nimbus debug download-bundle /tmp/nimbus-debug-bundle-max.zip \
  --limit 20000 \
  --service-log-line-limit 50000 \
  --max-mb 256

# Download the largest bundle currently allowed for a known UTC incident window.
nimbus debug download-bundle /tmp/nimbus-debug-bundle-window.zip \
  --from 2026-06-21T13:00:00Z \
  --to 2026-06-21T14:00:00Z \
  --limit 20000 \
  --service-log-line-limit 50000 \
  --max-mb 256

# Upload a temporary bundle to cloud and remove the temporary local file
nimbus debug upload-bundle

# Upload and retain a local copy at the requested path
nimbus debug upload-bundle --path /tmp/nimbus-debug-bundle.zip --max-mb 64