Collect and review Client Agent diagnostics

Running Client Agent diagnostics produces a ZIP bundle with diagnostic information about your system, network, Client Agent, and security environment. The Support team uses this bundle to investigate Client Agent connectivity, DNS, configuration, and runtime issues.

The bundle is stored locally in your Downloads folder by default, so you can review it before sharing it with Support.

Diagnostics typically complete in under five minutes, subject to a default 5-minute timeout.

When to run diagnostics

Run Client Agent diagnostics when you face problems such as:

The Client Agent starts, but sessions fail to connect or drop unexpectedly.
DNS resolution through the Client Agent fails or returns unexpected results.
The Client Agent reports errors, or its status differs from what you expect.
You open a support case for a Client Agent issue. Sharing a diagnostics bundle can help Support investigate the issue faster.

Prerequisites

Boundary Client Agent must be running on the host.
You must have write access to the destination directory. By default, it is your Downloads folder.
You must have about 5–10 MB of free disk space for the diagnostics bundle.

Run Client Agent diagnostics

You can run Client Agent diagnostics using the Boundary CLI or the Boundary Desktop Client.

Run the following command on the host where the Client Agent is running:

$ boundary client-agent diagnostics run

The run command starts the diagnostics collection process and prints progress until it completes. When the diagnostics collection finishes, it prints the path to the ZIP bundle:

Diagnostics information:
  Message:             Running diagnostics
  Progress (%):        0
  Status:              running

Diagnostics information:
  Message:             Running diagnostics
  Progress (%):        42
  Status:              running

Diagnostics information:
  Message:             Diagnostics complete. Review the bundle at the output path before you share it with Support.
  Output Path:         ~/Downloads/boundary-client-agent-diagnostics-<timestamp>.zip
  Progress (%):        100
  Status:              completed

For most cases, run on its own is sufficient. If you run diagnostics asynchronously, use the status and cancel commands to monitor or stop the diagnostics process.

The Client Agent allows one run per operating system user at a time and rejects a second run while one is running.

For the full command reference, refer to the client-agent CLI commands.

Where the Client Agent saves the bundle

By default, the Client Agent writes the bundle to your Downloads directory:

macOS: ~/Downloads
Windows: %USERPROFILE%\Downloads

The file name follows the pattern boundary-client-agent-diagnostics-<timestamp>.zip, where <timestamp> is the UTC time the diagnostics run starts. Use -output-path to save the bundle to a different directory.

Bundles follow a stable layout. A typical bundle tree contains the following:

boundary-client-agent-diagnostics-<timestamp>.zip
├── diagnostics.json        # JSON metadata about the run
├── agent/
│   ├── agentdetails.txt
│   ├── state.json
│   └── logs/
│       └── boundary-client-agent.log
├── network.txt
├── system.txt
└── security.txt

Network (network.txt): The file contains information about network interfaces, routes, DNS configuration, tunnel interfaces, and network connectivity. It also includes DNS resolution results and information about processes listening on port 53.
System (system.txt): The file contains information about your operating system, kernel, and CPU architecture.
Security (security.txt): The file contains information about security and VPN software, system extensions, tunnel interfaces, security-related services, and firewall status.
Agent (agent/): The directory contains Client Agent version, status, configuration, runtime state, and recent log entries.

The Client Agent diagnostics run collects the same set of files on macOS and Windows.

Extract the ZIP bundle and open diagnostics.json to confirm the run completed. If some diagnostic information cannot be collected, the Client Agent continues with the remaining diagnostics and still creates the bundle. You may receive the following errors:

partial_bundle: true — One or more files reported errors. The bundle is still usable, and the files that succeeded contain valid data. Check the individual files for more details.
timed_out: true - The diagnostics run exceeded its timeout, so some files may be missing.

The diagnostics run is designed to keep sensitive information out of the bundle. The bundle includes details specific to your environment to help Support understand what happens and troubleshoot your issue. Review the bundle before you share it, and remove anything you consider sensitive.

When you open a support case, attach the ZIP bundle and include:

A short summary of the problem and what you were trying to do when it occurred.
Any other details that may help explain the problem.

Support uses the information in the bundle, along with the details you provide, to troubleshoot and resolve the issue.

Resolve diagnostics errors

Use the following troubleshooting steps to resolve errors that can occur when you run Client Agent diagnostics:

Diagnostics output path is not accessible: The output directory does not exist or is not writable. Create the directory or pass a writable path with -output-path, then run the following commands:
```
mkdir -p ~/Downloads
chmod u+w ~/Downloads
```
A run is already in progress: The Client Agent allows one run per operating system user at a time. Wait for the current run to finish, or cancel it, then run the command again.
Run timed out: The run sets timed_out=true and produces a partial bundle. Run the command again to retry.