Configuration File

All server settings live in one YAML file:

Install type	Config file
System package (deb/rpm)	/etc/code.yaml
Userland install (no root)	~/.config/code/server.yaml
Docker / Podman	/etc/code.yaml on the host, mounted into the container

You can edit it by hand, or use the arrow-key editor — see The Setup TUI.

Annotated example

# --- listeners ---
listen: ":80"            # plain-HTTP listener. With HTTPS off this serves the
                         # app; with HTTPS on it answers certificate checks
                         # (ACME) and optionally redirects to https.
cookieSecure: true       # true once you serve HTTPS (required for sign-in to
                         # stick); false only for plain-HTTP testing.
hsts: false              # true = force HTTPS (redirect :80 → https and send
                         # the HSTS header). Turn on after HTTPS works.

# --- automatic HTTPS (Let's Encrypt) — see the HTTPS & Domain page ---
tlsDomains: ["code.example.com"]  # non-empty = HTTPS on; empty = plain HTTP
tlsListen: ":443"        # HTTPS port
tlsEmail: ""             # optional: email for certificate expiry notices

# --- storage ---
dataDir: ""              # empty = /var/lib/code/data. Holds machines,
                         # sessions, history, settings, and the cert cache.

# --- web UI (leave at defaults) ---
webDir: ""               # empty = /var/lib/code/web (installed by the package)

Key reference

Listeners & security

Key	Default	What it does
listen	":80"	Plain-HTTP address. When HTTPS is off, this serves the whole app. When HTTPS is on, it answers Let's Encrypt challenges and (with hsts: true) redirects everything else to HTTPS.
cookieSecure	false	Marks the sign-in cookie HTTPS-only. Set true in production. If you're signed out immediately after signing in, you probably set this to true while still browsing over plain http://.
hsts	false	Opt-in "HTTPS only" mode: plain HTTP gets redirected and browsers remember to always use HTTPS. Enable it once HTTPS is confirmed working.

HTTPS

Key	Default	What it does
tlsDomains	[]	Domain(s) to get free certificates for. Setting this is the switch that turns HTTPS on. Every listed domain must point at this server.
tlsListen	":443"	The HTTPS address.
tlsEmail	empty	Optional contact email for the certificate authority (expiry warnings).

Full walkthrough: HTTPS & Domain.

Storage & web UI

Key	Default	What it does
dataDir	/var/lib/code/data	Root of everything the server stores: bound machines and passwords, session history, settings, and the certificate cache. Back this up — see Data & Backup.
webDir	/var/lib/code/web	Where the built web UI is served from. The package puts it there; you normally never touch this.
webProxy	empty	Development only — leave empty.
corsOrigin	empty	Development only — leave empty.

Multi-node (optional)

Running several servers (e.g. one per region) and want the sign-in page to offer all of them with latency indicators? Two extra keys:

Key	What it does
serverList	The list of nodes shown on the binding page. Each entry: name, domain, optional ip / fallback, and https: true/false.
nodeName	Which serverList entry this server is. Leave empty on a single-server setup.

serverList:
  - { name: "Hong Kong", domain: "hk.example.com", https: true }
  - { name: "Singapore", domain: "sg.example.com", https: true }
nodeName: "Hong Kong"

Environment-variable overrides

Every key has a matching CODE_* environment variable that, when set, wins over the YAML value — e.g. CODE_LISTEN, CODE_TLS_DOMAINS (comma-separated), CODE_DATA_DIR, CODE_HSTS. This is mainly useful in container setups; on a normal install just edit the YAML.

WARNING

If a key is overridden by an environment variable (say, in the container definition), editing that key in the YAML has no effect until you remove the override.

Applying changes

• Easiest: edit with code-server-setup — saving with Ctrl+S reloads the running server automatically.
• Edited the file by hand? Restart: sudo systemctl restart code-server (userland: systemctl --user restart code-server).

A reload/restart drops active connections for a second or two; browsers and agents reconnect on their own and running tasks are not affected.