Generate a support bundle

To troubleshoot a deployment or workspace issue with Coder support, you can collect a support bundle from the CLI or VS Code. A support bundle is a ZIP archive of deployment, workspace, agent, and connection diagnostics.

Bundle contents

The CLI collects deployment and connection diagnostics, plus workspace and agent details when you specify a workspace. With workspace agent version 2.35.0 or later, agent logs include up to 10 MiB of the active log plus retained rotated logs modified in the last 24 hours, capped at 100 MiB in total. Older agents return only the active log. The lookback doesn't guarantee a full 24 hours of history because rotation can remove older logs. Additional workspace files are opt-in through --workspace-file. IDE integrations add their own diagnostics, which aren't included by the CLI alone.

Any authenticated user can generate a bundle. Your permissions, deployment configuration, and agent connectivity determine which data is available. Users with the Owner role get the most complete bundle; unavailable data can leave files empty or JSON values null.

Choose a collection method:

• CLI
• VS Code

Detailed archive contents

The archive contains the following files when the corresponding data is available:

Filename	Description
agent/agent.json	The agent used to connect to the workspace with environment variables stripped.
agent/agent_magicsock.html	The contents of the HTTP debug endpoint of the agent's Tailscale Wireguard connection.
agent/client_magicsock.html	The contents of the HTTP debug endpoint of the client's Tailscale Wireguard connection.
agent/listening_ports.json	The listening ports detected by the selected agent running in the workspace.
agent/logs.txt	Up to 10 MiB of the active agent log. Agents on version 2.35.0 or later also include retained rotated logs modified in the last 24 hours, capped at 100 MiB in total.
agent/workspace_files/collection_errors.txt	Workspace file entries dropped while assembling the bundle, such as entries exceeding the size budget. Only present when entries were dropped.
agent/workspace_files/files/	Files collected from inside the remote workspace with --workspace-file. Only present when workspace paths are requested.
agent/workspace_files/manifest.json	Describes the remote workspace file collection: requested patterns, collected files, per-path errors, truncation, and applied limits. Only present when workspace paths are requested.
agent/manifest.json	The manifest of the selected agent with environment variables stripped.
agent/startup_logs.txt	Startup logs of the workspace agent.
agent/peer_diagnostics.json	Connection details for the selected agent's peer.
agent/ping_result.json	Results of a connection check to the selected agent.
agent/prometheus.txt	The contents of the agent's Prometheus endpoint.
cli_logs.txt	Logs from running the coder support bundle command.
deployment/buildinfo.json	Coder version and build information.
deployment/config.json	Deployment configuration, with secret values removed. Requires Owner role.
deployment/experiments.json	Any experiments currently enabled for the deployment.
deployment/health.json	A snapshot of the health status of the deployment. Requires Owner role.
deployment/stats.json	Aggregated workspace and session metrics, subject to your permissions.
deployment/entitlements.json	Feature entitlements, when available.
deployment/health_settings.json	Dismissed health checks, subject to your permissions.
deployment/workspaces.json	Workspaces you can access, with agent environment values redacted. Limited to 10 workspaces by default.
deployment/prometheus.txt	Control plane Prometheus metrics, when enabled and accessible.
license-status.txt	License status, when available.
logs.txt	Logs from the codersdk.Client used to generate the bundle.
network/connection_info.json	Information used by workspace agents used to connect to Coder (DERP map etc.)
network/coordinator_debug.html	Peers currently connected to each Coder instance and the tunnels established between peers. Requires Owner role.
network/interfaces.json	Network interfaces on the machine running the CLI.
network/netcheck.json	Results of running coder netcheck locally.
network/tailnet_debug.html	Tailnet coordinators, their heartbeat ages, connected peers, and tunnels. Requires Owner role.
workspace/build_logs.txt	Build logs of the selected workspace.
workspace/workspace.json	Details of the selected workspace.
workspace/parameters.json	Build parameters of the selected workspace.
workspace/template.json	The template currently in use by the selected workspace.
workspace/template_file.zip	The source code of the template currently in use by the selected workspace.
workspace/template_version.json	The template version currently in use by the selected workspace.
templates/<name>/	Template details, active version, and source archive requested with --template.
pprof/	Control plane profiling data requested with --pprof; agent profiles are under pprof/agent/.
vscode-logs/	Only present when generated from the VS Code Coder Remote extension. Includes logs, selected settings, and local telemetry files.

Generate with the CLI

Use a machine on the network where you connect to your workspace so that the bundle captures that machine's connection diagnostics. Your Coder deployment must be available. A running, reachable workspace provides the most complete agent diagnostics.

1. Install the Coder CLI on your local machine.

2. Log in to your deployment.

3. Run the following command, replacing owner/workspace with your workspace's owner and name:

   coder support bundle owner/workspace

4. Review the collection notice and enter yes to confirm.

The CLI saves coder-support-<timestamp>.zip in the current directory and prints Wrote support bundle to followed by its path. To select an agent in a workspace with multiple agents, append its name: coder support bundle owner/workspace agent-name. If you omit the workspace when running inside one, the CLI infers the workspace and agent from the environment. Network diagnostics then reflect the workspace rather than your local machine. Outside a workspace, omitting the workspace produces deployment and local network diagnostics without workspace-specific data.

Include workspace files

To include editor or service logs from the workspace, add one --workspace-file flag per path or glob. These files come from the remote workspace, not from the machine running the CLI. Workspace file collection requires Coder version 2.36.0 or later for both the CLI and the workspace agent. The workspace agent must be reachable.

Run the following command with the paths you want to collect. Quote each pattern so that your local shell doesn't expand it:

After confirmation, the CLI writes a ZIP archive with collected files under agent/workspace_files/files/. The agent/workspace_files/manifest.json file records requested patterns, collected files, errors, truncation, and limits. An agent that doesn't support collection records that limitation in the manifest instead of collecting the requested files.

The workspace agent evaluates paths and globs:

• Environment variables such as $HOME expand inside the workspace.
• Paths must resolve to absolute paths or start with ~/, which resolves to the agent user's home directory.
• Direct paths follow symlinks; glob traversal doesn't follow symlinks.
• Collection is limited to 10,000 files and 100 MiB in total.
• Each file contributes at most its last 10 MiB, or less if the total budget is nearly exhausted, with truncation recorded in the manifest.

Customize collection

Use these options to adjust the bundle:

For all options, refer to the coder support bundle reference.

Generate from your IDE

Use your IDE's collection action to include its local diagnostics alongside the Coder bundle. Running the CLI separately doesn't collect those local IDE files.

VS Code

Use the Coder Remote extension version 1.16.0 or later for this workflow. Sign in to your Coder deployment in the extension before collecting a bundle.

• Bundle generation requires Coder version 2.10.0 or later.
• Remote editor server log collection requires Coder version 2.36.0 or later, including a reachable workspace agent on that version or later.

By default, the extension downloads a CLI that matches your deployment. If you configure a custom CLI, it must also meet these version requirements.

1. Open the Command Palette.
2. Run Coder: Create Support Bundle.
3. If prompted, select a running workspace.
4. Review Create a support bundle? and select Continue.
5. Choose a local destination in Save Support Bundle. The extension confirms the saved archive's location and offers Reveal in File Explorer.
6. Review the archive before sharing it.

You can also open the context menu for a running workspace or one of its agents in the Coder sidebar and select Support Bundle. To target a specific agent when you aren't connected, start from that agent's context menu.

The extension runs coder support bundle and adds local diagnostics under vscode-logs/:

• Coder extension logs from recent windows and sessions.
• SSH proxy and Remote-SSH logs.
• Selected VS Code settings.
• Local telemetry files, when available.

The extension masks configured values for coder.globalFlags, coder.headerCommand, and coder.tlsCertRefreshCommand. Other collected settings, including deployment URLs, TLS file paths, and SSH flags, are included unchanged. Review these values before sharing.

Extension version 1.16.1 or later adds session identifiers and logs workspace and agent state changes. With extension version 1.16.4 or later, bundles can include recent connection logs even if you didn't turn on debug logging. Collection is best effort, so the latest entries may be missing. To turn off buffering, set coder.connectionLogBuffer.size to 0.

Remote editor server logs appear under agent/workspace_files/, separately from the local VS Code diagnostics.

For telemetry controls and retention, refer to VS Code local telemetry. For extension installation and settings, refer to the Coder Remote README.

Review and share the bundle

1. Extract the ZIP archive.
2. Review its contents and remove sensitive information before sharing.
3. Create a new ZIP archive from the reviewed contents.
4. Upload the reviewed archive through the link Coder support provides.

Include a description of the issue and any supporting files requested by Coder support.