code-server User Guide

Run VS Code in your browser, anywhere. code-server wraps Visual Studio Code's web server with its own authentication, reverse proxy, and CLI layer so you can access a full VS Code environment from any device with a browser. Built and maintained by Coder.

1. Quick Start

Get code-server running in under five minutes on any Linux machine:

# 1. Install
curl -fsSL https://code-server.dev/install.sh | sh

# 2. Start the service
sudo systemctl enable --now code-server@$USER

# 3. Get your auto-generated password
cat ~/.config/code-server/config.yaml

Open http://127.0.0.1:8080 in your browser, enter the password shown in the config file, and you are in VS Code.

Tip

The install script auto-detects your OS and package manager. It works on Debian/Ubuntu, Fedora/CentOS/RHEL, openSUSE, Arch, Alpine, FreeBSD, and macOS. Run with --dry-run first to see what it will do without making changes.

Quick Start with Docker

docker run -it --name code-server \
  -p 127.0.0.1:8080:8080 \
  -v "$HOME/.local:/home/coder/.local" \
  -v "$HOME/.config:/home/coder/.config" \
  -v "$PWD:/home/coder/project" \
  -u "$(id -u):$(id -g)" \
  -e "DOCKER_USER=$USER" \
  codercom/code-server:latest

Then open http://127.0.0.1:8080 and use the password from ~/.config/code-server/config.yaml inside the container.

2. Installation

2.1 Install Script (Recommended)

The official install script handles detection of your OS and installs via the appropriate package manager:

curl -fsSL https://code-server.dev/install.sh | sh

Install script flags:

What the script installs, by platform:

2.2 Homebrew (macOS and Linux)

brew install code-server

After installing, start the service:

brew services start code-server

2.3 npm

Requires Node.js 22.

npm install -g code-server

Then run directly:

code-server

2.4 Docker

Official images are available for multiple base distributions:

# Standard image (Debian-based)
docker pull codercom/code-server

# Run with persistent config and project mount
docker run -d --name code-server \
  -p 127.0.0.1:8080:8080 \
  -v "$HOME/.config:/home/coder/.config" \
  -v "$PWD:/home/coder/project" \
  codercom/code-server:latest

Note

The Docker image runs as the coder user by default. Set the DOCKER_USER environment variable to rename this user to match your host user. Files in the ENTRYPOINTD directory (if present) are executed as startup scripts.

Docker init systems: The standard image uses dumb-init; alternative images may use catatonit.

2.5 Helm Chart

For Kubernetes deployments:

helm repo add code-server https://helm.coder.com/code-server
helm install code-server code-server/code-server

Chart version 3.35.0 ships with code-server appVersion 4.116.0.

2.6 Devcontainer Feature

code-server is available as a Dev Container Feature for use in devcontainer configurations.

2.7 systemd Service

Package installs (deb, rpm, AUR, Homebrew) set up a systemd service automatically. Enable and start it:

sudo systemctl enable --now code-server@$USER

Check status:

sudo systemctl status code-server@$USER

View logs:

journalctl -u code-server@$USER -f

3. Configuration

3.1 Config File

On first run, code-server generates a default config file:

• Linux / macOS: ~/.config/code-server/config.yaml
• Windows: %APPDATA%\code-server\config.yaml

Override the path with --config /path/to/config.yaml or the CODE_SERVER_CONFIG environment variable.

Default generated config:

bind-addr: 127.0.0.1:8080
auth: password
password: <randomly-generated>
cert: false

Any CLI flag can be set in this YAML file using its long name (without --). The config file is the recommended place for sensitive values like password, hashed-password, and github-auth because these are stripped from the process environment after being read.

Important

The password, hashed-password, and github-auth options should only be set in the config file or via environment variables (PASSWORD, HASHED_PASSWORD, GITHUB_TOKEN). They are intentionally not accepted as command-line arguments to avoid exposure in process listings.

Example config with common options:

bind-addr: 0.0.0.0:8443
auth: password
hashed-password: "$argon2i$v=19$m=4096,t=3,p=1$..."
cert: /etc/ssl/certs/code-server.crt
cert-key: /etc/ssl/private/code-server.key
disable-telemetry: true
disable-update-check: true
log: info

3.2 Environment Variables

Environment variables override config file values:

Note

Sensitive environment variables (PASSWORD, HASHED_PASSWORD, GITHUB_TOKEN) are cleared from the process environment immediately after being read for security.

3.3 Command-Line Flags

CLI flags take the highest precedence, overriding both config file and environment variables. The full reference is in the CLI Reference section below.

Precedence order (highest to lowest):

1. Command-line flags
2. Environment variables
3. Config file (config.yaml)
4. Built-in defaults

3.4 Data Directories

code-server stores its data in platform-specific locations:

Tip

On macOS, code-server uses XDG-style paths (~/.local/share and ~/.config), not native macOS directories like ~/Library/Application Support. This is intentional for cross-platform consistency.

Override these with:

• --user-data-dir for the data directory
• --extensions-dir for installed extensions
• --config for the config file location

4. Core Usage

4.1 Starting code-server

Basic start (uses config file defaults):

code-server

Bind to all interfaces on a custom port:

code-server --bind-addr 0.0.0.0:9000

Listen on a Unix socket instead of TCP:

code-server --socket /run/code-server/code-server.sock --socket-mode 660

Open a specific folder:

code-server /path/to/project

Open browser automatically (local machine only):

code-server --open /path/to/project

4.2 Authentication

Password Authentication (Default)

code-server uses password authentication by default. The password is set in one of three ways:

1. Auto-generated on first run (saved to config.yaml)
2. Plain text via password in config file or PASSWORD environment variable
3. Hashed via hashed-password in config file or HASHED_PASSWORD environment variable

To generate an argon2 hash for your password:

echo -n "your-password" | npx argon2-cli -e

Then set it in your config:

auth: password
hashed-password: "$argon2i$v=19$m=4096,t=3,p=1$..."

Warning

Login attempts are rate-limited to 2 per minute and 12 per hour. If you exceed these limits, you will be temporarily locked out. There is no way to bypass this without restarting code-server.

No Authentication

For development or trusted networks where access is already controlled (e.g., behind a VPN):

code-server --auth none

Or in config.yaml:

auth: none

4.3 TLS / HTTPS

Using Your Own Certificate

code-server --cert /path/to/cert.pem --cert-key /path/to/key.pem

Or in config.yaml:

cert: /path/to/cert.pem
cert-key: /path/to/key.pem

Self-Signed Certificate

Pass --cert without a value to generate a self-signed certificate:

code-server --cert

Use --cert-host to set the hostname on the self-signed certificate:

code-server --cert --cert-host myhost.example.com

Caution

Self-signed certificates will trigger browser warnings. For production use, obtain a proper certificate from a CA or use a reverse proxy (nginx, Caddy, Traefik) that handles TLS termination.

4.4 Managing Extensions

Install Extensions

# By extension ID
code-server --install-extension ms-python.python

# Specific version
code-server --install-extension ms-python.python@2024.0.1

# From VSIX file
code-server --install-extension ./my-extension.vsix

# Skip confirmation prompts
code-server --install-extension ms-python.python --force

List Installed Extensions

code-server --list-extensions

# With version numbers
code-server --list-extensions --show-versions

Uninstall Extensions

code-server --uninstall-extension ms-python.python

Custom Extension Gallery

By default, code-server uses the Open VSX Registry. To configure a custom gallery (such as a private registry), set the EXTENSIONS_GALLERY environment variable:

export EXTENSIONS_GALLERY='{"serviceUrl":"https://my-registry.example.com/api"}'
code-server

Enable Proposed API

Some extensions require VS Code's proposed API:

code-server --enable-proposed-api publisher.extension-name

4.5 Progressive Web App (PWA)

code-server supports installation as a Progressive Web App. When you visit code-server in a supported browser (Chrome, Edge, etc.), you will see an "Install" option in the browser's address bar or menu. Installing as a PWA provides:

• A dedicated window without browser chrome
• An app icon on your desktop/dock
• Faster launch times

The PWA uses 192px and 512px icons in both regular and maskable formats.

4.6 Internationalization (i18n)

code-server ships with built-in translations for:

• English (default)
• Chinese Simplified (zh-cn)
• Thai
• Japanese
• Urdu

Set the display language:

code-server --locale zh-cn

Use custom translations:

Create a JSON file with your custom strings and pass it with --i18n:

code-server --i18n /path/to/custom-strings.json

Custom strings are merged with the built-in defaults, so you only need to include the strings you want to override.

5. Common Tasks

5.1 Exposing code-server to the Internet

By default, code-server binds to 127.0.0.1:8080 (localhost only). To access it remotely, you have several options:

Option A: Reverse Proxy (Recommended)

Place code-server behind a reverse proxy that handles TLS and authentication. Example nginx configuration:

server {
    listen 443 ssl;
    server_name code.example.com;

    ssl_certificate /etc/ssl/certs/code.example.com.crt;
    ssl_certificate_key /etc/ssl/private/code.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Important

WebSocket support is required. Ensure your proxy passes Upgrade and Connection headers as shown above. Without WebSocket support, code-server will not function correctly.

When using a reverse proxy, you may need to configure trusted origins:

code-server --trusted-origins "https://code.example.com"

The --trusted-origins flag supports wildcards: *.example.com matches all subdomains.

Option B: SSH Tunnel

Forward the port through SSH without exposing anything publicly:

ssh -N -L 8080:127.0.0.1:8080 user@your-server

Then access http://127.0.0.1:8080 locally.

Option C: Direct Binding (Use with Caution)

Bind to all interfaces directly. Only do this with TLS and strong authentication:

code-server --bind-addr 0.0.0.0:8443 --cert /path/to/cert.pem --cert-key /path/to/key.pem

5.2 Port Proxying

code-server can proxy requests to services running on other ports of the same machine. This is useful for previewing web applications during development.

Path-Based Proxy

Access any local port through code-server's URL:

• /proxy/:port/ -- Rewrites paths relative to the base. Best for apps that expect to run at the root path.
• /absproxy/:port/ -- Passes the full path through unchanged. The proxied application must be aware of its prefix path.

Example: If your app runs on port 3000, access it at:

https://your-code-server/proxy/3000/

Use --abs-proxy-base-path to set a custom prefix for absproxy requests.

Domain-Based Proxy

Configure wildcard subdomains that map to ports:

code-server --proxy-domain "{{port}}.proxy.example.com"

With this configuration, 3000.proxy.example.com proxies to localhost:3000. You can also use a prefix format:

code-server --proxy-domain "prefix-{{port}}.example.com"

Tip

Domain-based proxying requires wildcard DNS (e.g., *.proxy.example.com) pointing to your code-server host, plus a wildcard TLS certificate. Path-based proxying works without any DNS setup.

All proxy routes support WebSocket connections.

To disable all proxy routes entirely:

code-server --disable-proxy

VS Code Ports Tab

To enable the Ports tab in VS Code's panel (for forwarding ports from the integrated terminal), set the VSCODE_PROXY_URI environment variable:

export VSCODE_PROXY_URI="https://{{port}}.proxy.example.com"
code-server

5.3 Running Multiple Instances

To run multiple code-server instances on the same machine (e.g., for different projects or users):

1. Use different ports:

   code-server --bind-addr 127.0.0.1:8080 --config ~/.config/code-server/project-a.yaml /path/to/project-a
   code-server --bind-addr 127.0.0.1:8081 --config ~/.config/code-server/project-b.yaml /path/to/project-b
   

2. Set unique cookie suffixes to prevent session conflicts:

   code-server --cookie-suffix project-a --bind-addr 127.0.0.1:8080
   code-server --cookie-suffix project-b --bind-addr 127.0.0.1:8081
   

3. Use separate data directories if you want isolated extension sets:

   code-server --user-data-dir ~/.local/share/code-server-a --extensions-dir ~/.local/share/code-server-a/extensions
   

5.4 Disabling Features

code-server provides flags to lock down specific capabilities:

5.5 Auto-Shutdown on Idle

For cloud instances where you want to save resources:

code-server --idle-timeout-seconds 900

This shuts down code-server after 15 minutes (900 seconds) of inactivity. The value must be greater than 60 seconds.

You can also set it via environment variable:

export CODE_SERVER_IDLE_TIMEOUT_SECONDS=900
code-server

5.6 Customizing the Appearance

Application Name

Replace the default "code-server" branding in the title bar and welcome page:

code-server --app-name "My Dev Environment"

The --app-name (short: -an) flag replaces the {{app}} placeholder in UI strings.

Link Protection Trusted Domains

When clicking external links, code-server shows a confirmation dialog. To skip this for trusted domains:

code-server --link-protection-trusted-domains "github.com" --link-protection-trusted-domains "*.example.com"

5.7 Reconnection Behavior

When your browser loses connection (network blip, laptop sleep, etc.), code-server will attempt to reconnect. The grace period before a full reload is required defaults to 10,800 seconds (3 hours):

# Reduce to 30 minutes
code-server --reconnection-grace-time 1800

Or via environment variable:

export CODE_SERVER_RECONNECTION_GRACE_TIME=1800

5.8 Working Behind a Corporate Proxy

If your server accesses the internet through a proxy:

export HTTP_PROXY="http://proxy.corp.example.com:8080"
export HTTPS_PROXY="http://proxy.corp.example.com:8080"
code-server

This affects outbound connections for extension downloads, update checks, and GitHub API calls.

5.9 Health Checks and Monitoring

code-server exposes a health endpoint for load balancers and monitoring:

curl http://127.0.0.1:8080/healthz

Response:

{"status": "alive", "lastHeartbeat": 1714000000000}

The status field returns "alive" under normal operation or "expired" if the server has been idle past its timeout. A WebSocket endpoint is also available at /healthz.

Update check endpoint:

curl "http://127.0.0.1:8080/update/check?force=true"

Response:

{
  "checked": 1714000000000,
  "latest": "4.116.0",
  "current": "4.115.0",
  "isLatest": false
}

This checks the GitHub releases API. By default, it caches results for 24 hours; use force=true to bypass the cache.

5.10 Window Behavior Flags

Control how code-server opens projects:

6. Troubleshooting

6.1 Cannot Connect After Install

Error: Browser shows "connection refused" or times out when accessing http://127.0.0.1:8080.

Cause: code-server is not running, or is bound to a different address/port.

Solution:

1. Check if code-server is running:

   sudo systemctl status code-server@$USER
   

2. Verify the bind address in ~/.config/code-server/config.yaml
3. Check logs for startup errors:

   journalctl -u code-server@$USER -e
   

Prevention: Always verify the config file settings match your expectations before starting the service.

6.2 Password Not Working

Error: Correct password is rejected at the login screen.

Cause: Rate limiting (2 per minute / 12 per hour), or password mismatch between config file and what you are entering.

Solution:

1. Wait for the rate limit to reset (up to 1 hour for the hourly limit)
2. Verify your password:

   cat ~/.config/code-server/config.yaml | grep password
   

3. If using HASHED_PASSWORD, verify it was generated correctly. hashed-password takes precedence over password.
4. Restart code-server after changing password settings:

   sudo systemctl restart code-server@$USER
   

Prevention: Use the PASSWORD environment variable for automation, and verify with a test login immediately after changing passwords.

6.3 Cannot Find argon2 Module

Error: Cannot find module 'argon2' when using hashed passwords.

Cause: The argon2 native module was not compiled for your platform during installation.

Solution: This issue has been fixed in current releases. Upgrade to the latest version:

curl -fsSL https://code-server.dev/install.sh | sh

6.4 WebSocket Connection Fails Behind Reverse Proxy

Error: VS Code features partially work but terminals, extensions, and live updates fail.

Cause: The reverse proxy is not forwarding WebSocket connections.

Solution: Ensure your proxy passes the Upgrade and Connection headers. For nginx:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection upgrade;

Prevention: Always test WebSocket connectivity after setting up a reverse proxy. Open a terminal in code-server; if it works, WebSockets are functioning.

6.5 Extensions From VS Code Marketplace Not Available

Error: You cannot find extensions that exist in the VS Code Marketplace.

Cause: code-server uses the Open VSX Registry by default, not Microsoft's VS Code Marketplace. Not all extensions are published to Open VSX.

Solution:

1. Check if the extension exists on open-vsx.org
2. Install manually via VSIX:

   code-server --install-extension ./downloaded-extension.vsix
   

3. Configure a custom gallery via EXTENSIONS_GALLERY if you host your own registry

6.6 Homebrew Install Missing vscode.git Extension

Error: The built-in Git extension is missing or broken after Homebrew installation.

Cause: Known issue (GitHub #7758) with some Homebrew builds.

Solution: Reinstall using the official install script instead:

brew uninstall code-server
curl -fsSL https://code-server.dev/install.sh | sh

6.7 Copilot Chat Does Not Work

Error: GitHub Copilot Chat extension does not function.

Cause: Known limitation (GitHub #7494). Some proprietary Microsoft extensions have compatibility issues with code-server.

Solution: This is a known issue being tracked upstream. Check the GitHub issue for current status and workarounds.

6.8 Random Text Insertion

Error: Random characters appear in the editor without typing.

Cause: Known issue (GitHub #7707) potentially related to input handling in certain browser/OS combinations.

Solution:

1. Try a different browser
2. Disable browser extensions that intercept keyboard input
3. Check if the issue persists in an incognito/private window

6.9 Workspace Trust Prompt Appears Repeatedly

Error: code-server keeps asking to trust the workspace on every session.

Cause: Known issue (GitHub #7703) where Workspace Trust state may not persist correctly.

Solution: Disable the prompt entirely:

code-server --disable-workspace-trust

6.10 Verbose Logging for Debugging

When reporting issues or diagnosing problems, enable maximum logging:

code-server --verbose

The --verbose flag (short: -vvv) sets the log level to trace, which captures all diagnostic information. You can also set specific levels:

code-server --log debug

Or via environment variable:

export LOG_LEVEL=trace
code-server

Available log levels: trace, debug, info, warn, error.

7. FAQ

Q: Is code-server the same as VS Code?

code-server runs the actual VS Code editor (pulled in as a git submodule with patches applied on top). The editing experience is identical. The difference is the surrounding infrastructure: code-server adds its own authentication layer, reverse proxy for port forwarding, CLI flags, and config file management. You get the real VS Code, just delivered through your browser instead of a desktop Electron app.

Q: What Node.js version does code-server require?

Node.js 22. If you install via the install script, Docker, or Homebrew, Node.js is handled for you. You only need to manage Node.js yourself if installing via npm.

Q: Can I use the same extensions as desktop VS Code?

code-server uses the Open VSX Registry by default. Most popular open-source extensions are available there. For extensions only on Microsoft's marketplace, you can download the VSIX file and install it manually with --install-extension ./file.vsix, or configure a custom gallery via the EXTENSIONS_GALLERY environment variable.

Q: How do I update code-server?

Re-run the install script:

curl -fsSL https://code-server.dev/install.sh | sh

For Docker, pull the latest image. For Homebrew, run brew upgrade code-server. For npm, run npm update -g code-server.

Q: Can I run code-server on Windows?

code-server runs natively on Linux and macOS. On Windows, the recommended approach is to run it inside WSL2 (Windows Subsystem for Linux) or Docker.

Q: How do I change the default port?

Three ways, in order of precedence:

1. CLI: code-server --bind-addr 0.0.0.0:3000
2. Environment: export PORT=3000
3. Config: set bind-addr: 127.0.0.1:3000 in config.yaml

Q: Is my traffic encrypted?

Not by default. code-server binds to localhost on HTTP. For remote access, either: (a) use --cert to enable TLS directly, (b) place it behind a TLS-terminating reverse proxy, or (c) access it through an SSH tunnel.

Q: Can I use code-server on a tablet or phone?

Yes. code-server works in any modern browser. Install it as a PWA for the best experience on mobile devices -- you get a dedicated app window and a home screen icon. Touch input works, though a keyboard (Bluetooth or on-screen) is recommended for serious coding.

Q: How do I share my code-server with a teammate?

Each user should have their own code-server instance with their own authentication. Run multiple instances on different ports with separate configs, data directories, and cookie suffixes. See Running Multiple Instances.

Q: What is the session cookie and how long does it last?

code-server sets a code-server-session cookie (optionally suffixed with --cookie-suffix). The session persists until the browser is closed or the cookie expires. The reconnection grace time (default 3 hours) determines how long a disconnected session can resume without re-authenticating.

Q: What happens if code-server crashes? Will I lose my work?

VS Code auto-saves your work to the data directory. When you restart code-server, your open files and unsaved changes should be recovered through VS Code's built-in recovery mechanism, just like the desktop version.

CLI Reference

Complete list of all command-line flags. Every flag can also be set in the YAML config file using its long name (without --).

Server Options

Authentication Options

Extension Options

Proxy Options

Feature Flags

Display and Behavior Options

Info Options