# 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](https://coder.com).

---

## 1. Quick Start

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

```bash
# 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

```bash
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:

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

**Install script flags:**

| Flag | Purpose |
|------|---------|
| `--dry-run` | Preview what the script will do without making changes |
| `--version X.X.X` | Install a specific version |
| `--edge` | Install the latest pre-release |
| `--method detect` | Auto-detect best install method (default) |
| `--method standalone` | Force standalone (tarball) install |
| `--prefix /path` | Set install prefix for standalone method |
| `--rsh /path/to/bin` | Use alternate remote shell binary |

**What the script installs, by platform:**

| Platform | Method |
|----------|--------|
| Debian / Ubuntu | `.deb` package |
| Fedora / CentOS / RHEL / openSUSE | `.rpm` package |
| Arch Linux | AUR package |
| Alpine / FreeBSD | npm global install |
| macOS | Homebrew formula |
| Other Linux | Standalone tarball |

### 2.2 Homebrew (macOS and Linux)

```bash
brew install code-server
```

After installing, start the service:

```bash
brew services start code-server
```

### 2.3 npm

Requires **Node.js 22**.

```bash
npm install -g code-server
```

Then run directly:

```bash
code-server
```

### 2.4 Docker

Official images are available for multiple base distributions:

```bash
# 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:

```bash
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](https://containers.dev/features) 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:

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

Check status:

```bash
sudo systemctl status code-server@$USER
```

View logs:

```bash
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:**

```yaml
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:**

```yaml
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:

| Variable | Purpose |
|----------|---------|
| `PASSWORD` | Set the login password |
| `HASHED_PASSWORD` | Set an argon2 hashed password (takes precedence over `PASSWORD`) |
| `GITHUB_TOKEN` | GitHub authentication token |
| `PORT` | Override the port (overrides bind-addr port) |
| `CODE_SERVER_HOST` | Override the host (overrides bind-addr host) |
| `CODE_SERVER_CONFIG` | Path to custom config file |
| `CS_DISABLE_FILE_DOWNLOADS` | Set to `true` or `1` to disable file downloads |
| `CS_DISABLE_GETTING_STARTED_OVERRIDE` | Set to `true` or `1` to disable Getting Started override |
| `CS_DISABLE_PROXY` | Set to `true` or `1` to disable proxy routes |
| `CODE_SERVER_COOKIE_SUFFIX` | Suffix for session cookies (useful with multiple instances on subdomains) |
| `CODE_SERVER_IDLE_TIMEOUT_SECONDS` | Shut down after this many idle seconds (must be >60) |
| `CODE_SERVER_RECONNECTION_GRACE_TIME` | Seconds before a disconnect requires a full reload (default: 10800 / 3 hours) |
| `LOG_LEVEL` | Set log level: `trace`, `debug`, `info`, `warn`, `error` |
| `EXTENSIONS_GALLERY` | JSON string for a custom extensions marketplace |
| `HTTP_PROXY` / `HTTPS_PROXY` | Proxy settings for outbound connections |
| `VSCODE_PROXY_URI` | URI template for VS Code's Ports tab |

> [!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](#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:

| Platform | Data Directory | Config Directory |
|----------|---------------|-----------------|
| Linux | `~/.local/share/code-server` | `~/.config/code-server` |
| macOS | `~/.local/share/code-server` | `~/.config/code-server` |
| Windows | `%APPDATA%\code-server` | `%APPDATA%\code-server` |

> [!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):**

```bash
code-server
```

**Bind to all interfaces on a custom port:**

```bash
code-server --bind-addr 0.0.0.0:9000
```

**Listen on a Unix socket instead of TCP:**

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

**Open a specific folder:**

```bash
code-server /path/to/project
```

**Open browser automatically (local machine only):**

```bash
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:

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

Then set it in your config:

```yaml
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):

```bash
code-server --auth none
```

Or in `config.yaml`:

```yaml
auth: none
```

### 4.3 TLS / HTTPS

#### Using Your Own Certificate

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

Or in `config.yaml`:

```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:

```bash
code-server --cert
```

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

```bash
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

```bash
# 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

```bash
code-server --list-extensions

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

#### Uninstall Extensions

```bash
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:

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

#### Enable Proposed API

Some extensions require VS Code's proposed API:

```bash
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:**

```bash
code-server --locale zh-cn
```

**Use custom translations:**

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

```bash
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:

```nginx
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:**
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:

| Flag / Env Var | Effect |
|----------------|--------|
| `--disable-file-downloads` / `CS_DISABLE_FILE_DOWNLOADS` | Prevents downloading files from the editor |
| `--disable-file-uploads` | Prevents uploading files to the editor |
| `--disable-proxy` / `CS_DISABLE_PROXY` | Disables all proxy routes (path, absolute, and domain) |
| `--disable-workspace-trust` | Disables Workspace Trust prompts for the session |
| `--disable-getting-started-override` / `CS_DISABLE_GETTING_STARTED_OVERRIDE` | Disables Coder's Getting Started page override |
| `--disable-telemetry` | Disables telemetry collection |
| `--disable-update-check` | Disables the automatic update check (normally runs every 6 hours, notifies weekly) |

### 5.5 Auto-Shutdown on Idle

For cloud instances where you want to save resources:

```bash
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:

```bash
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:

```bash
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:

```bash
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)**:

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

Or via environment variable:

```bash
export CODE_SERVER_RECONNECTION_GRACE_TIME=1800
```

### 5.8 Working Behind a Corporate Proxy

If your server accesses the internet through a proxy:

```bash
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:

```bash
curl http://127.0.0.1:8080/healthz
```

**Response:**

```json
{"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:**

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

**Response:**

```json
{
  "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:

| Flag | Short | Behavior |
|------|-------|----------|
| `--ignore-last-opened` | `-e` | Do not restore the last opened folder/workspace |
| `--new-window` | `-n` | Force opening in a new window |
| `--reuse-window` | `-r` | Force reusing the existing window |

---

## 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:
   ```bash
   sudo systemctl status code-server@$USER
   ```
2. Verify the bind address in `~/.config/code-server/config.yaml`
3. Check logs for startup errors:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:
```bash
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:
```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](https://open-vsx.org)
2. Install manually via VSIX:
   ```bash
   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:
```bash
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:
```bash
code-server --disable-workspace-trust
```

### 6.10 Verbose Logging for Debugging

When reporting issues or diagnosing problems, enable maximum logging:

```bash
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:

```bash
code-server --log debug
```

Or via environment variable:

```bash
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:
```bash
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](#53-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

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--bind-addr` | | `host:port` | `127.0.0.1:8080` | Address and port to bind to |
| `--socket` | | string | | Listen on a Unix socket (overrides `--bind-addr`) |
| `--socket-mode` | | string | | File permissions for the Unix socket |
| `--cert` | | string (optional) | `false` | Path to TLS certificate. Pass without value for self-signed |
| `--cert-host` | | string | | Hostname for self-signed certificate generation |
| `--cert-key` | | string | | Path to TLS certificate private key |
| `--open` | | boolean | `false` | Open browser on startup (local connections only) |
| `--log` | | string | `info` | Log level: `trace`, `debug`, `info`, `warn`, `error` |
| `--verbose` | `-vvv` | boolean | `false` | Set log level to `trace` |
| `--config` | | string | (platform default) | Path to YAML config file |

### Authentication Options

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--auth` | `password` or `none` | `password` | Authentication type |
| `--password` | string | (auto-generated) | Login password (config file / env only) |
| `--hashed-password` | string | | Argon2 hashed password (config file / env only, takes precedence) |
| `--github-auth` | string | | GitHub token (config file / env only) |
| `--trusted-origins` | string[] | | Origins that skip the Origin header check. Supports `*` and `*.domain` wildcards |
| `--skip-auth-preflight` | boolean | `false` | Allow preflight (CORS) requests without authentication |
| `--cookie-suffix` | string | | Suffix appended to session cookie name |

### Extension Options

| Flag | Type | Description |
|------|------|-------------|
| `--install-extension` | string[] | Install extension(s) by ID (`publisher.name[@version]`) or VSIX path |
| `--uninstall-extension` | string[] | Uninstall extension(s) by ID |
| `--list-extensions` | boolean | List all installed extensions |
| `--show-versions` | boolean | Show version numbers with `--list-extensions` |
| `--force` | boolean | Skip confirmation prompts during extension operations |
| `--enable-proposed-api` | string[] | Enable proposed API for specified extensions |
| `--extensions-dir` | string | Custom directory for installed extensions |

### Proxy Options

| Flag | Type | Description |
|------|------|-------------|
| `--proxy-domain` | string[] | Domain template for port proxying. Format: `{{port}}.domain.tld` or `prefix-{{port}}.domain.tld` |
| `--disable-proxy` | boolean | Disable all proxy routes |
| `--abs-proxy-base-path` | string | Base path prefix for absolute proxy requests |

### Feature Flags

| Flag | Short | Type | Description |
|------|-------|------|-------------|
| `--disable-telemetry` | | boolean | Disable telemetry |
| `--disable-update-check` | | boolean | Disable update check (checks every 6h, notifies weekly) |
| `--disable-file-downloads` | | boolean | Disable file download capability |
| `--disable-file-uploads` | | boolean | Disable file upload capability |
| `--disable-workspace-trust` | | boolean | Disable Workspace Trust for the session |
| `--disable-getting-started-override` | | boolean | Disable Coder Getting Started page override |

### Display and Behavior Options

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--app-name` | `-an` | string | `code-server` | Custom application name (replaces `{{app}}` in UI strings) |
| `--welcome-text` | `-w` | string | | Login page text (deprecated) |
| `--locale` | | string | | Display language (IETF language tag) |
| `--i18n` | | string | | Path to JSON with custom i18n translations (merged with defaults) |
| `--link-protection-trusted-domains` | | string[] | | Domains that skip the external link confirmation dialog |
| `--idle-timeout-seconds` | | number | | Shut down after this many idle seconds (must be >60) |
| `--reconnection-grace-time` | | string | `10800` | Seconds before disconnect requires full reload |
| `--ignore-last-opened` | `-e` | boolean | | Do not restore last opened folder/workspace |
| `--new-window` | `-n` | boolean | | Force opening in a new window |
| `--reuse-window` | `-r` | boolean | | Force reusing existing window |
| `--user-data-dir` | | string | (platform default) | Custom user data directory |

### Info Options

| Flag | Short | Description |
|------|-------|-------------|
| `--help` | `-h` | Show help text |
| `--version` | `-v` | Show version information |

---

_Generated May 2026 from coder/code-server at 5f7c23b. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._