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.
Coder server is configured primarily through environment variables.
This page lists every option so you can search by environment variable name, CLI flag, or YAML key.
For first-time setup guidance and worked examples, see Configure Control Plane Access.
Each option can be set through one or more of the methods below.
An option lists only the methods that apply to it.
An environment variable (recommended for production deployments running as a system service, container, or Helm chart).
A CLI flag passed to coder server (useful for one-off invocations and local development).
A key in a YAML configuration file passed with --config.
For a full description of each option's accepted values and behavior, follow the flag link into the coder server CLI reference.
An option that holds a secret is marked as such.
Coder never writes those options to a YAML configuration file.
Deprecated options are listed at the end of each section.
General
Cache directory
The directory to cache temporary files.
If unspecified and $CACHE_DIRECTORY is set, it will be used for compatibility with systemd.
This directory is NOT safe to be configured as a shared directory across coderd/provisionerd replicas.
The default lifetime duration for API tokens.
This value is used when creating a token without specifying a duration, such as when authenticating the CLI or an IDE plugin.
Disable caller-supplied tools in chats.
Chat requests that include unsafe_dynamic_tools or inline_mcp_servers are rejected, and existing chats run without their dynamic tools and inline MCP servers.
Remove the permission for the 'owner' role to have workspace execution on all workspaces.
This prevents the 'owner' from ssh, apps, and terminal access based on the 'owner' role.
They still have their user permissions to access their own workspaces.
Disable workspace apps that are not served from subdomains.
Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript.
This is recommended for security purposes if a --wildcard-access-url is configured.
Stop persisting workspace agent context snapshots (instructions, skills, and MCP state used for pinned chat context).
When set, coderd rejects agent context pushes as unimplemented and agents stop sending them; chats cannot pin workspace context.
Use this to shed the database write load of context sync on large deployments.
Disable workspace sharing.
Workspace ACL checking is disabled and only owners can have ssh, apps and terminal access to workspaces.
Access based on the 'owner' role is also allowed unless disabled via --disable-owner-workspace-access.
Enable one or more experiments.
These are not ready for production.
Separate multiple experiments with commas, or enter '*' to opt-in to all available experiments.
Encrypt OIDC and Git authentication tokens with AES-256-GCM in the database.
The value must be a comma-separated list of base64-encoded keys.
Each key, when base64-decoded, must be exactly 32 bytes in length.
The first key will be used to encrypt new values.
Subsequent keys will be used as a fallback when decrypting.
During normal operation it is recommended to only set one key unless you are in the process of rotating keys with the coder server dbcrypt rotate command.
Maximum number of idle connections to the database.
Set to "auto" (the default) to use max open / 3.
Value must be greater or equal to 0; 0 means explicitly no idle connections.
URL of a PostgreSQL database.
If empty, PostgreSQL binaries will be downloaded from Maven (https://repo1.maven.org/maven2) and store all data in the config root.
Access the built-in database with "coder server postgres-builtin-url".
Note that any special characters in the URL must be URL-encoded.
Determines the effective group when a user belongs to multiple groups with AI budgets. "highest" selects the group with the largest spend limit, and is currently the only supported value.
Base directory for dumping AI Gateway request/response pairs to disk for debugging.
When set, each provider writes under a subdirectory named after the provider.
Sensitive headers are redacted.
Leave empty to disable.
Header name for the authenticated user's email address.
Empty disables this header.
Requires AI Gateway actor headers to be enabled.
Applies to every configured provider; email is personal information.
Stop recording the content of intercepted conversations.
No user prompt, tool call or model reasoning record is stored, including tool names and the arguments they were called with.
Interceptions and token usage are still recorded, so cost controls, budget enforcement and spend reporting are unaffected.
Sessions show no conversation detail, prompt and tool call telemetry report zero, and interceptions are no longer grouped into threads for clients that do not send their own session ID.
Combine with --ai-gateway-structured-logging-source=gateway to keep exporting these records to a SIEM instead.
Add configured headers identifying the authenticated user to intercepted upstream requests.
Use this when a proxy between AI Gateway and an upstream AI provider needs user identity.
When enabled, removes client-supplied headers at configured actor-header destinations before adding authenticated values.
Client headers starting with X-AI-Bridge-Actor are always removed.
Which process emits AI Gateway interception records when structured logging is enabled: coderd, the gateway, or both.
The gateway emits records that are never persisted, such as those dropped by --ai-gateway-disable-content-recording, but cannot report thread_parent_id or thread_root_id.
Use both to verify a move from one to the other; records reaching coderd are then reported twice.
A standalone gateway must be configured to emit its own records, and its logs shipped rather than coderd's.
Directory for dumping MITM request/response pairs to disk for debugging.
When set, each proxied request produces .req.txt and .resp.txt files organized by provider.
Sensitive headers are redacted.
Leave empty to disable.
Comma-separated list of CIDR ranges that are permitted even though they fall within blocked private/reserved IP ranges.
By default all private ranges are blocked to prevent SSRF attacks.
Use this to allow access to specific internal networks.
Path to the CA certificate file used to intercept (MITM) HTTPS traffic from AI clients.
This CA must be trusted by AI clients for the proxy to decrypt their requests.
Base URL of the AI Gateway to forward intercepted requests to.
Defaults to the embedded AI Gateway address at the Coder access URL plus /api/v2/ai-gateway.
URL of an upstream HTTP proxy to chain tunneled (non-allowlisted) requests through.
Format: http://[user:pass@]host:port or https://[user:pass@]host:port.
Path to a PEM-encoded CA certificate to trust for the upstream proxy's TLS connection.
Only needed for HTTPS upstream proxies with certificates not trusted by the system.
If not provided, the system certificate pool is used.
Maximum number of files linked to a chat, including user uploads, files the agent attaches, and desktop recordings and their thumbnails.
Linking a file beyond the limit permanently deletes the chat's earliest-uploaded files, and earlier messages show them as expired.
A message that includes more files than the limit is rejected with HTTP 400.
Must be at least 1.
Maximum number of virtual desktop recordings that each Coder server stores at the same time.
Each upload holds the recording and its thumbnail in memory, up to 110 MB.
Additional recordings wait for a free slot and are discarded if none frees up within 90 seconds.
Must be at least 1.
Maximum number of consecutive retries after a model generation fails with a transient error, such as a rate limit, an overloaded provider, or a stream that stops sending data.
The count resets after each successful step.
When the retries run out, the chat moves to the error state and shows the provider error.
Advisor calls and the generation of chat titles, summaries, and turn status labels use the same limit.
Must be at least 1.
Maximum size in bytes of the deployment system prompt, the plan mode instructions, and each user's custom prompt.
Saving a longer prompt fails with HTTP 400.
Lowering the limit does not affect prompts that are already saved.
Must be at least 1.
Maximum number of steps in a chat turn.
Each model response is one step; compaction summaries, advisor calls, and retried attempts do not count.
A turn that reaches the limit runs the tools from the last response, then ends without an error.
Must be at least 1.
Maximum time to wait for the next streamed part from the chat model before the attempt is canceled and retried.
This also bounds the time to first token.
Set to 0 to disable.
Must be no more than 24h.
These options change the behavior of how clients interact with the Coder.
Clients include the Coder CLI, Coder Desktop, IDE extensions, and the web UI.
CLI upgrade message
The upgrade message to display to users when a client/server mismatch is detected.
By default it instructs users to update using 'curl -fsSL https://coder.com/install.sh | sh'.
These SSH config options will override the default SSH config options.
Provide options in "key=value" or "key value" format separated by commas.
Using this incorrectly can break SSH to your deployment, use cautiously.
The following options are not allowed: Host, Match, Include, ProxyCommand, ProxyJump, LocalCommand, PermitLocalCommand, RemoteCommand, KnownHostsCommand, PKCS11Provider, SecurityKeyProvider, SmartcardDevice, XAuthLocation.
Option values must not contain newline, carriage return, or NUL characters.
Workspace hostnames use this suffix in SSH config and Coder Connect on Coder Desktop.
By default it is coder, resulting in names like myworkspace.coder.
The suffix must not start with a dot, and must not contain spaces, newlines, or glob characters (* and ?).
The threshold for the database health check.
If the median latency of the database exceeds this threshold over 5 attempts, the database is considered unhealthy.
The default value is 15ms.
When collecting agent stats, aggregate metrics by a given set of comma-separated labels to reduce cardinality.
Accepted values are agent_name, template_name, username, workspace_name.
Enable the collection of application and workspace usage along with the associated API endpoints and the template insights page.
Disabling this will also disable traffic and connection insights in the deployment stats shown to admins in the bottom bar of the Coder UI, and will prevent Prometheus collection of these values.
Enables capturing of logs as events in traces.
This is useful for debugging, but may result in a very large amount of events being sent to the tracing backend which may incur significant costs.
MCP server destinations in private or reserved IP ranges are blocked by default for SSRF protection.
This applies to OAuth2 discovery, OAuth2 token and revocation exchanges, and runtime MCP connections from coderd.
This option exempts specific CIDRs.
Recommended to be enabled.
Enables __Host- prefix for cookies to guarantee they are only set by the right domain.
This change is disruptive to any workspaces built before release 2.31, requiring a workspace restart.
Most Coder deployments never have to think about DERP because all connections between workspaces and users are peer-to-peer.
However, when Coder cannot establish a peer to peer connection, Coder uses a distributed relay network backed by Tailscale and WireGuard.
Block direct connections
Block peer-to-peer (aka. direct) workspace connections.
All workspace connections from the CLI will be proxied through Coder (or custom configured DERP servers) and will never be peer-to-peer when enabled.
Workspaces may still reach out to STUN servers to get their address until they are restarted after this change has been made, but new connections will still be proxied regardless.
Force clients and agents to always use WebSocket to connect to DERP relay servers.
By default, DERP uses Upgrade: derp, which may cause issues with some reverse proxies.
Clients may automatically fallback to WebSocket if they detect an issue with Upgrade: derp, but this does not work in all situations.
Addresses for STUN servers to establish P2P connections.
It's recommended to have at least two STUN servers to give users the best chance of connecting P2P to workspaces.
Each STUN server will get it's own DERP region, with region IDs starting at --derp-server-region-id + 1.
Use special value 'disable' to turn off STUN completely.
Coder configures a Content Security Policy (CSP) to protect against XSS attacks.
This setting allows you to add additional CSP directives, which can open the attack surface of the deployment.
Format matches the CSP directive format, e.g. --additional-csp-policy="script-src https://example.com".
Disable password authentication.
This is recommended for security purposes in production deployments that rely on an identity provider.
Any user with the owner role will be able to sign in with their password regardless of this setting to avoid potential lock out.
If you are locked out of your account, you can use the coder server create-admin command to create a new admin user directly in the database.
Disable automatic session expiry bumping due to activity.
This forces all sessions to become invalid after the session expiry duration has been reached.
The token expiry duration for browser sessions.
Sessions may last longer if they are actively making requests, but this functionality can be disabled via --disable-session-expiry-refresh.
Configure TLS / HTTPS for your Coder deployment.
If you're running Coder behind a TLS-terminating reverse proxy or are accessing Coder over a secure link, you can safely ignore these settings.
Strict-Transport-Security
Controls if the 'Strict-Transport-Security' header is set on all static file responses.
This header should only be set if the server is accessed via HTTPS.
This value is the MaxAge in seconds of the header.
Two optional fields can be set in the Strict-Transport-Security header; 'includeSubDomains' and 'preload'.
The 'strict-transport-security' flag must be set to a non-zero value for these options to be used.
Path to each certificate for TLS.
It requires a PEM-encoded file.
To configure the listener to use a CA certificate, concatenate the primary certificate and the CA certificate together.
The primary certificate should appear first in the combined file.
Policy the server will follow for TLS Client Authentication.
Accepted values are "none", "request", "require-any", "verify-if-given", or "require-and-verify".
Enable the OAuth 2.1 authorization server, which lets external applications (such as MCP clients) obtain tokens for Coder on behalf of users.
Disabled by default.
When disabled, the OAuth2 endpoints and discovery documents return 404.
If provided any group name not in the list will not be allowed to authenticate.
This allows for restricting access to a specific set of groups.
This filter is applied after the group mapping and before the regex filter.
Pem encoded certificate file to use for oauth2 PKI/JWT authorization.
The public certificate that accompanies oidc-client-key-file.
A standard x509 certificate is expected.
Optional override of the default redirect url which uses the deployment's access url.
Useful in situations where a deployment has more than 1 domain.
Using this setting can also break OIDC, so use with caution.
If provided any group name not matching the regex is ignored.
This allows for filtering out groups that are not needed.
This filter is applied after the group mapping.
This field must be set if using the user roles sync feature.
Set this to the name of the claim used to store the user's role.
The roles should be sent as an array of strings.
A map of the OIDC passed in user roles and the groups in Coder it should map to.
This is useful if the group names do not match.
If mapped to the empty string, the role will ignored.
OIDC issuer urls must match in the request, the id_token 'iss' claim, and in the well-known configuration.
This flag disables that requirement, and can lead to an insecure OIDC configuration.
It is not recommended to use this flag.
Tune the behavior of the provisioner, which is responsible for creating, updating, and deleting workspace resources.
Disable Terraform module cache
Disable the reuse of Terraform modules cached at template import for all templates.
Modules are re-downloaded on every workspace build.
Individual templates cannot opt back in.
Configure data retention policies for various database tables.
Retention policies automatically purge old data to reduce database size and improve performance.
Setting a retention duration to 0 disables automatic purging for that data type.
API keys retention
How long expired API keys are retained before being deleted.
Keeping expired keys allows the backend to return a more helpful error when a user tries to use an expired key.
Set to 0 to disable automatic deletion of expired keys.
How long audit log entries are retained.
Set to 0 to disable (keep indefinitely).
We advise keeping audit logs for at least a year, and in accordance with your compliance requirements.
How long boundary audit log entries are retained.
Boundary logs record HTTP requests processed by a Boundary confinement proxy.
Set to 0 to disable automatic deletion (keep indefinitely).
Adjust to match your organization's regulatory requirements.
How long workspace agent logs are retained.
Logs from non-latest builds are deleted if the agent hasn't connected within this period.
Logs from the latest build are always retained.
Set to 0 to disable automatic deletion.
Telemetry is critical to our ability to improve Coder.
We strip all personal information before sending data to our servers.
Please only disable telemetry when required by your organization's security policy.
Enable
Whether telemetry is enabled or not.
Coder collects anonymized usage data to help improve our product.
The module registry host the template builder uses for module source paths (for example, "registry.coder.com" or "mirror.internal:8443").
An http(s):// scheme and trailing slash are stripped; a path, query, fragment, or credentials is rejected.
Allow users to set quiet hours schedules each day for workspaces to avoid workspaces stopping during the day due to template scheduling.
Allow custom quiet hours
Allow users to set their own quiet hours schedule for workspaces to stop in (depending on template autostop requirement settings).
If false, users can't change their quiet hours schedule and the site default is always used.
The default daily cron schedule applied to users that haven't set a custom quiet hours schedule themselves.
The quiet hours schedule determines when workspaces will be force stopped due to the template's autostop requirement, and will round the max deadline up to be within the user's quiet hours window (or default).
The format is the same as the standard cron format, but the day-of-month, month and day-of-week must be *.
Only one hour and minute can be specified (ranges or comma separated values are not supported).
These options can break your deployment or weaken its security.
Change them only when you understand the consequences.
Allow path app sharing
Allow workspace apps that are not served from subdomains to be shared.
Path-based app sharing is DISABLED by default for security purposes.
Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript.
Path-based apps can be disabled entirely with --disable-path-apps for further security.
Allow site-owners to access workspace apps from workspaces they do not own.
Owners cannot access path-based apps they do not own by default.
Path-based apps can make requests to the Coder API and pose a security risk when the workspace serves malicious JavaScript.
Path-based apps can be disabled entirely with --disable-path-apps for further security.
