Coder powers secure, scalable development across key industries — automotive, finance, government, and technology — enabling faster builds, tighter compliance, and seamless AI adoption in enterprise-grade cloud environments.
When you engage with Coder support to diagnose an issue with your deployment,
you may be asked to generate and upload a "Support Bundle" for offline analysis.
This document explains the contents of a support bundle and the steps to submit
a support bundle to Coder staff.
What is a Support Bundle?
A support bundle is an archive containing a snapshot of information about your
Coder deployment.
It contains information about the workspace, the template it uses, running
agents in the workspace, and other detailed information useful for
troubleshooting.
It is primarily intended for troubleshooting connectivity issues to workspaces,
but can be useful for diagnosing other issues as well.
While we attempt to redact sensitive information from support bundles, they
may contain information deemed sensitive by your organization and should be
treated as such.
A brief overview of all files contained in the bundle is provided below:
Note
Detailed descriptions of all the information available in the bundle is
out of scope, as support bundles are primarily intended for internal use.
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
Active agent log plus rotated agent logs modified in the last 24 hours, capped at 100 MiB.
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/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.
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/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.
vscode-logs/
Only present when generated from the VS Code Coder Remote extension. Includes logs, redacted settings, and local telemetry files.
How do I generate a Support Bundle?
Ensure your deployment is up and running. Generating a support bundle
requires the Coder deployment to be available.
Ensure you have the Coder CLI installed on a local machine. See
installation for steps on how to do this.
Note
It is recommended to generate a support bundle from a location
experiencing workspace connectivity issues.
Ensure you are logged in to your Coder
deployment. Any authenticated user can generate a support bundle. Users with
the Owner role will get the most complete bundle; non-admin users will still
get a useful bundle but some admin-only data will be omitted (see the note
below).
Run coder support bundle [owner/workspace], and respond yes to the
prompt. The support bundle will be generated in the current directory with
the filename coder-support-$TIMESTAMP.zip.
If you use VS Code, you can also run Coder: Create Support Bundle from
the Command Palette. The VS Code Coder Remote extension runs
coder support bundle and appends recent VS Code diagnostics to the
generated archive. Bundles created with the CLI alone do not include
vscode-logs/. Learn more about
VS Code diagnostics.
Note
While support bundles can be generated without a running workspace, it is
recommended to specify one to maximize troubleshooting information.
To collect workspace-side files such as editor or service logs, add one
--workspace-file flag for each path or glob. This is explicit
opt-in. The CLI sends each value to the workspace agent, so quote globs to
prevent your local shell from expanding them:
coder support bundle my-workspace \
--workspace-file '$HOME/.vscode-server/data/logs/**/*.log' \
--workspace-file '$HOME/.local/share/code-server/coder-logs/**/*.log'
Workspace paths and globs are evaluated by the workspace agent.
Environment variables such as $HOME expand in the workspace, and ~/
resolves against the agent user's home directory; any absolute path in
the workspace can be requested. Symlinks are followed for directly
requested paths, but not during glob traversal. Collection is limited to
10000 files and 100 MiB in total; files larger than 10 MiB are truncated
to their last 10 MiB and marked as truncated in the manifest. Collected
files are stored under agent/workspace_files/files/, and collection
metadata is stored in agent/workspace_files/manifest.json.
Warning
Workspace files can contain tokens, credentials, source code, or other
sensitive data. Extract and review agent/workspace_files/ before sharing
the bundle.
(Recommended) Extract the support bundle and review its contents, redacting
any information you deem necessary.
Coder staff will provide you a link where you can upload the bundle along
with any other necessary supporting files.
Note
It is helpful to leave an informative message regarding the nature of
supporting files.
Coder support will then review the information you provided and respond to you
with next steps.
