coder/docs/cli/server.md

server

Start a Coder server

Usage

coder server [flags]

Subcommands

Name	Purpose
create-admin-user	Create a new admin user with the given username, email and password and adds it to every organization.
postgres-builtin-serve	Run the built-in PostgreSQL deployment.
postgres-builtin-url	Output the connection URL for the built-in PostgreSQL deployment.

Options

--access-url

Type	url
Environment	$CODER_ACCESS_URL
YAML	networking.accessURL

The URL that users will use to access the Coder deployment.

--browser-only

Type	bool
Environment	$CODER_BROWSER_ONLY
YAML	networking.browserOnly

Whether Coder only allows connections to workspaces via the browser.

--cache-dir

Type	string
Environment	$CODER_CACHE_DIRECTORY
YAML	cacheDir
Default	~/.cache/coder

The directory to cache temporary files. If unspecified and $CACHE_DIRECTORY is set, it will be used for compatibility with systemd.

--trace-logs

Type	bool
Environment	$CODER_TRACE_LOGS
YAML	introspection.tracing.captureLogs

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. If the verbose flag was supplied, debug-level logs will be included.

-c, --config

Type	yaml-config-path
Environment	$CODER_CONFIG_PATH

Specify a YAML file to load configuration from.

--dangerous-allow-path-app-sharing

Type	bool
Environment	$CODER_DANGEROUS_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.

--dangerous-allow-path-app-site-owner-access

Type	bool
Environment	$CODER_DANGEROUS_ALLOW_PATH_APP_SITE_OWNER_ACCESS

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.

--derp-config-path

Type	string
Environment	$CODER_DERP_CONFIG_PATH
YAML	networking.derp.configPath

Path to read a DERP mapping from. See: https://tailscale.com/kb/1118/custom-derp-servers/.

--derp-config-url

Type	string
Environment	$CODER_DERP_CONFIG_URL
YAML	networking.derp.url

URL to fetch a DERP mapping on startup. See: https://tailscale.com/kb/1118/custom-derp-servers/.

--derp-server-enable

Type	bool
Environment	$CODER_DERP_SERVER_ENABLE
YAML	networking.derp.enable
Default	true

Whether to enable or disable the embedded DERP relay server.

--derp-server-region-code

Type	string
Environment	$CODER_DERP_SERVER_REGION_CODE
YAML	networking.derp.regionCode
Default	coder

Region code to use for the embedded DERP server.

--derp-server-region-id

Type	int
Environment	$CODER_DERP_SERVER_REGION_ID
YAML	networking.derp.regionID
Default	999

Region ID to use for the embedded DERP server.

--derp-server-region-name

Type	string
Environment	$CODER_DERP_SERVER_REGION_NAME
YAML	networking.derp.regionName
Default	Coder Embedded Relay

Region name that for the embedded DERP server.

--derp-server-relay-url

Type	url
Environment	$CODER_DERP_SERVER_RELAY_URL
YAML	networking.derp.relayURL

An HTTP URL that is accessible by other replicas to relay DERP traffic. Required for high availability.

--derp-server-stun-addresses

Type	string-array
Environment	$CODER_DERP_SERVER_STUN_ADDRESSES
YAML	networking.derp.stunAddresses
Default	stun.l.google.com:19302

Addresses for STUN servers to establish P2P connections. Set empty to disable P2P connections.

--disable-owner-workspace-access

Type	bool
Environment	$CODER_DISABLE_OWNER_WORKSPACE_ACCESS
YAML	disableOwnerWorkspaceAccess

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-password-auth

Type	bool
Environment	$CODER_DISABLE_PASSWORD_AUTH
YAML	networking.http.disablePasswordAuth

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-path-apps

Type	bool
Environment	$CODER_DISABLE_PATH_APPS
YAML	disablePathApps

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.

--disable-session-expiry-refresh

Type	bool
Environment	$CODER_DISABLE_SESSION_EXPIRY_REFRESH
YAML	networking.http.disableSessionExpiryRefresh

Disable automatic session expiry bumping due to activity. This forces all sessions to become invalid after the session expiry duration has been reached.

--swagger-enable

Type	bool
Environment	$CODER_SWAGGER_ENABLE
YAML	enableSwagger

Expose the swagger endpoint via /swagger.

--experiments

Type	string-array
Environment	$CODER_EXPERIMENTS
YAML	experiments

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.

--provisioner-force-cancel-interval

Type	duration
Environment	$CODER_PROVISIONER_FORCE_CANCEL_INTERVAL
YAML	provisioning.forceCancelInterval
Default	10m0s

Time to force cancel provisioning tasks that are stuck.

--http-address

Type	string
Environment	$CODER_HTTP_ADDRESS
YAML	networking.http.httpAddress
Default	127.0.0.1:3000

HTTP bind address of the server. Unset to disable the HTTP endpoint.

--log-human

Type	string
Environment	$CODER_LOGGING_HUMAN
YAML	introspection.logging.humanPath
Default	/dev/stderr

Output human-readable logs to a given file.

--log-json

Type	string
Environment	$CODER_LOGGING_JSON
YAML	introspection.logging.jsonPath

Output JSON logs to a given file.

--max-token-lifetime

Type	duration
Environment	$CODER_MAX_TOKEN_LIFETIME
YAML	networking.http.maxTokenLifetime
Default	876600h0m0s

The maximum lifetime duration users can specify when creating an API token.

--oauth2-github-allow-everyone

Type	bool
Environment	$CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
YAML	oauth2.github.allowEveryone

Allow all logins, setting this option means allowed orgs and teams must be empty.

--oauth2-github-allow-signups

Type	bool
Environment	$CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS
YAML	oauth2.github.allowSignups

Whether new users can sign up with GitHub.

--oauth2-github-allowed-orgs

Type	string-array
Environment	$CODER_OAUTH2_GITHUB_ALLOWED_ORGS
YAML	oauth2.github.allowedOrgs

Organizations the user must be a member of to Login with GitHub.

--oauth2-github-allowed-teams

Type	string-array
Environment	$CODER_OAUTH2_GITHUB_ALLOWED_TEAMS
YAML	oauth2.github.allowedTeams

Teams inside organizations the user must be a member of to Login with GitHub. Structured as: /.

--oauth2-github-client-id

Type	string
Environment	$CODER_OAUTH2_GITHUB_CLIENT_ID
YAML	oauth2.github.clientID

Client ID for Login with GitHub.

--oauth2-github-client-secret

Type	string
Environment	$CODER_OAUTH2_GITHUB_CLIENT_SECRET

Client secret for Login with GitHub.

--oauth2-github-enterprise-base-url

Type	string
Environment	$CODER_OAUTH2_GITHUB_ENTERPRISE_BASE_URL
YAML	oauth2.github.enterpriseBaseURL

Base URL of a GitHub Enterprise deployment to use for Login with GitHub.

--oidc-allow-signups

Type	bool
Environment	$CODER_OIDC_ALLOW_SIGNUPS
YAML	oidc.allowSignups
Default	true

Whether new users can sign up with OIDC.

--oidc-auth-url-params

Type	struct[map[string]string]
Environment	$CODER_OIDC_AUTH_URL_PARAMS
YAML	oidc.authURLParams
Default	{"access_type": "offline"}

OIDC auth URL parameters to pass to the upstream provider.

--oidc-client-id

Type	string
Environment	$CODER_OIDC_CLIENT_ID
YAML	oidc.clientID

Client ID to use for Login with OIDC.

--oidc-client-secret

Type	string
Environment	$CODER_OIDC_CLIENT_SECRET

Client secret to use for Login with OIDC.

--oidc-email-domain

Type	string-array
Environment	$CODER_OIDC_EMAIL_DOMAIN
YAML	oidc.emailDomain

Email domains that clients logging in with OIDC must match.

--oidc-email-field

Type	string
Environment	$CODER_OIDC_EMAIL_FIELD
YAML	oidc.emailField
Default	email

OIDC claim field to use as the email.

--oidc-group-field

Type	string
Environment	$CODER_OIDC_GROUP_FIELD
YAML	oidc.groupField

Change the OIDC default 'groups' claim field. By default, will be 'groups' if present in the oidc scopes argument.

--oidc-group-mapping

Type	struct[map[string]string]
Environment	$CODER_OIDC_GROUP_MAPPING
YAML	oidc.groupMapping
Default	{}

A map of OIDC group IDs and the group in Coder it should map to. This is useful for when OIDC providers only return group IDs.

--oidc-ignore-email-verified

Type	bool
Environment	$CODER_OIDC_IGNORE_EMAIL_VERIFIED
YAML	oidc.ignoreEmailVerified

Ignore the email_verified claim from the upstream provider.

--oidc-ignore-userinfo

Type	bool
Environment	$CODER_OIDC_IGNORE_USERINFO
YAML	oidc.ignoreUserInfo
Default	false

Ignore the userinfo endpoint and only use the ID token for user information.

--oidc-issuer-url

Type	string
Environment	$CODER_OIDC_ISSUER_URL
YAML	oidc.issuerURL

Issuer URL to use for Login with OIDC.

--oidc-scopes

Type	string-array
Environment	$CODER_OIDC_SCOPES
YAML	oidc.scopes
Default	openid,profile,email

Scopes to grant when authenticating with OIDC.

--oidc-username-field

Type	string
Environment	$CODER_OIDC_USERNAME_FIELD
YAML	oidc.usernameField
Default	preferred_username

OIDC claim field to use as the username.

--oidc-sign-in-text

Type	string
Environment	$CODER_OIDC_SIGN_IN_TEXT
YAML	oidc.signInText
Default	OpenID Connect

The text to show on the OpenID Connect sign in button.

--oidc-icon-url

Type	url
Environment	$CODER_OIDC_ICON_URL
YAML	oidc.iconURL

URL pointing to the icon to use on the OepnID Connect login button.

--provisioner-daemon-poll-interval

Type	duration
Environment	$CODER_PROVISIONER_DAEMON_POLL_INTERVAL
YAML	provisioning.daemonPollInterval
Default	1s

Time to wait before polling for a new job.

--provisioner-daemon-poll-jitter

Type	duration
Environment	$CODER_PROVISIONER_DAEMON_POLL_JITTER
YAML	provisioning.daemonPollJitter
Default	100ms

Random jitter added to the poll interval.

--postgres-url

Type	string
Environment	$CODER_PG_CONNECTION_URL

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".

--prometheus-address

Type	host:port
Environment	$CODER_PROMETHEUS_ADDRESS
YAML	introspection.prometheus.address
Default	127.0.0.1:2112

The bind address to serve prometheus metrics.

--prometheus-collect-agent-stats

Type	bool
Environment	$CODER_PROMETHEUS_COLLECT_AGENT_STATS
YAML	introspection.prometheus.collect_agent_stats

Collect agent stats (may increase charges for metrics storage).

--prometheus-enable

Type	bool
Environment	$CODER_PROMETHEUS_ENABLE
YAML	introspection.prometheus.enable

Serve prometheus metrics on the address defined by prometheus address.

--provisioner-daemons

Type	int
Environment	$CODER_PROVISIONER_DAEMONS
YAML	provisioning.daemons
Default	3

Number of provisioner daemons to create on start. If builds are stuck in queued state for a long time, consider increasing this.

--proxy-trusted-headers

Type	string-array
Environment	$CODER_PROXY_TRUSTED_HEADERS
YAML	networking.proxyTrustedHeaders

Headers to trust for forwarding IP addresses. e.g. Cf-Connecting-Ip, True-Client-Ip, X-Forwarded-For.

--proxy-trusted-origins

Type	string-array
Environment	$CODER_PROXY_TRUSTED_ORIGINS
YAML	networking.proxyTrustedOrigins

Origin addresses to respect "proxy-trusted-headers". e.g. 192.168.1.0/24.

--redirect-to-access-url

Type	bool
Environment	$CODER_REDIRECT_TO_ACCESS_URL
YAML	networking.redirectToAccessURL

Specifies whether to redirect requests that do not match the access URL host.

--scim-auth-header

Type	string
Environment	$CODER_SCIM_AUTH_HEADER

Enables SCIM and sets the authentication header for the built-in SCIM server. New users are automatically created with OIDC authentication.

--ssh-config-options

Type	string-array
Environment	$CODER_SSH_CONFIG_OPTIONS
YAML	client.sshConfigOptions

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.

--ssh-hostname-prefix

Type	string
Environment	$CODER_SSH_HOSTNAME_PREFIX
YAML	client.sshHostnamePrefix
Default	coder.

The SSH deployment prefix is used in the Host of the ssh config.

--ssh-keygen-algorithm

Type	string
Environment	$CODER_SSH_KEYGEN_ALGORITHM
YAML	sshKeygenAlgorithm
Default	ed25519

The algorithm to use for generating ssh keys. Accepted values are "ed25519", "ecdsa", or "rsa4096".

--secure-auth-cookie

Type	bool
Environment	$CODER_SECURE_AUTH_COOKIE
YAML	networking.secureAuthCookie

Controls if the 'Secure' property is set on browser session cookies.

--session-duration

Type	duration
Environment	$CODER_SESSION_DURATION
YAML	networking.http.sessionDuration
Default	24h0m0s

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.

--log-stackdriver

Type	string
Environment	$CODER_LOGGING_STACKDRIVER
YAML	introspection.logging.stackdriverPath

Output Stackdriver compatible logs to a given file.

--strict-transport-security

Type	int
Environment	$CODER_STRICT_TRANSPORT_SECURITY
YAML	networking.tls.strictTransportSecurity
Default	0

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.

--strict-transport-security-options

Type	string-array
Environment	$CODER_STRICT_TRANSPORT_SECURITY_OPTIONS
YAML	networking.tls.strictTransportSecurityOptions

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.

--tls-address

Type	host:port
Environment	$CODER_TLS_ADDRESS
YAML	networking.tls.address
Default	127.0.0.1:3443

HTTPS bind address of the server.

--tls-cert-file

Type	string-array
Environment	$CODER_TLS_CERT_FILE
YAML	networking.tls.certFiles

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.

--tls-client-auth

Type	string
Environment	$CODER_TLS_CLIENT_AUTH
YAML	networking.tls.clientAuth
Default	none

Policy the server will follow for TLS Client Authentication. Accepted values are "none", "request", "require-any", "verify-if-given", or "require-and-verify".

--tls-client-ca-file

Type	string
Environment	$CODER_TLS_CLIENT_CA_FILE
YAML	networking.tls.clientCAFile

PEM-encoded Certificate Authority file used for checking the authenticity of client.

--tls-client-cert-file

Type	string
Environment	$CODER_TLS_CLIENT_CERT_FILE
YAML	networking.tls.clientCertFile

Path to certificate for client TLS authentication. It requires a PEM-encoded file.

--tls-client-key-file

Type	string
Environment	$CODER_TLS_CLIENT_KEY_FILE
YAML	networking.tls.clientKeyFile

Path to key for client TLS authentication. It requires a PEM-encoded file.

--tls-enable

Type	bool
Environment	$CODER_TLS_ENABLE
YAML	networking.tls.enable

Whether TLS will be enabled.

--tls-key-file

Type	string-array
Environment	$CODER_TLS_KEY_FILE
YAML	networking.tls.keyFiles

Paths to the private keys for each of the certificates. It requires a PEM-encoded file.

--tls-min-version

Type	string
Environment	$CODER_TLS_MIN_VERSION
YAML	networking.tls.minVersion
Default	tls12

Minimum supported version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13".

--telemetry

Type	bool
Environment	$CODER_TELEMETRY_ENABLE
YAML	telemetry.enable
Default	true

Whether telemetry is enabled or not. Coder collects anonymized usage data to help improve our product.

--telemetry-trace

Type	bool
Environment	$CODER_TELEMETRY_TRACE
YAML	telemetry.trace
Default	true

Whether Opentelemetry traces are sent to Coder. Coder collects anonymized application tracing to help improve our product. Disabling telemetry also disables this option.

--trace

Type	bool
Environment	$CODER_TRACE_ENABLE
YAML	introspection.tracing.enable

Whether application tracing data is collected. It exports to a backend configured by environment variables. See: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md.

--trace-honeycomb-api-key

Type	string
Environment	$CODER_TRACE_HONEYCOMB_API_KEY

Enables trace exporting to Honeycomb.io using the provided API Key.

--update-check

Type	bool
Environment	$CODER_UPDATE_CHECK
YAML	updateCheck
Default	false

Periodically check for new releases of Coder and inform the owner. The check is performed once per day.

-v, --verbose

Type	bool
Environment	$CODER_VERBOSE
YAML	introspection.logging.verbose

Output debug-level logs.

--wildcard-access-url

Type	url
Environment	$CODER_WILDCARD_ACCESS_URL
YAML	networking.wildcardAccessURL

Specifies the wildcard hostname to use for workspace applications in the form "*.example.com".

--write-config

Type	bool

Write out the current server config as YAML to stdout.

--pprof-address

Type	host:port
Environment	$CODER_PPROF_ADDRESS
YAML	introspection.pprof.address
Default	127.0.0.1:6060

The bind address to serve pprof.

--pprof-enable

Type	bool
Environment	$CODER_PPROF_ENABLE
YAML	introspection.pprof.enable

Serve pprof metrics on the address defined by pprof address.