# coder/code-server architecture

> Architecture diagram of the GitHub repository coder/code-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coder/code-server
- Repository: https://github.com/coder/code-server

## Overview

code-server runs the VS Code server on a remote machine and serves its browser client over HTTP and WebSockets. The principal workflow is CLI configuration and startup, HTTP/WebSocket routing, authentication, then dispatch to VS Code or optional forwarded services; users interact with the resulting browser IDE. The README emphasizes remote development and consistent environments, while the tree and excerpts show operational capabilities such as login, proxying, updates, health checks, and workspace opening. Some route wiring is only partly excerpted, so unverified links are omitted.

Main entry points: [`src/node/routes/index.ts`](https://github.com/coder/code-server/blob/main/src/node/routes/index.ts) (Route registration), [`src/node/main.ts`](https://github.com/coder/code-server/blob/main/src/node/main.ts) (Server lifecycle), [`src/node/app.ts`](https://github.com/coder/code-server/blob/main/src/node/app.ts) (HTTP app server), [`src/node/routes/vscode.ts`](https://github.com/coder/code-server/blob/main/src/node/routes/vscode.ts) (VS Code routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and configuration"]
  node_cli["CLI configuration<br/>[cli.ts]"]
  node_entry["Process entry<br/>[entry.ts]"]
  node_main["Server lifecycle<br/>[main.ts]"]
  node_settings[("Persistent settings<br/>[settings.ts]")]
end

subgraph group_transport["HTTP and WebSocket"]
  node_httpapp["HTTP app server<br/>[app.ts]"]
  node_httphelpers["HTTP security helpers<br/>[http.ts]"]
  node_wsrouter["WebSocket dispatch<br/>[wsRouter.ts]"]
  node_events["Event emitter<br/>[emitter.ts]"]
  node_httpcommon["HTTP primitives<br/>[http.ts]"]
end

subgraph group_access["Access and routing"]
  node_routes["Route registration<br/>[index.ts]"]
  node_login["Login and logout<br/>[login.ts]"]
  node_health["Health checks<br/>[health.ts]"]
  node_domainproxy["Domain forwarding<br/>[domainProxy.ts]"]
  node_pathproxy["Port forwarding<br/>[pathProxy.ts]"]
  node_updateroute["Update endpoint<br/>[update.ts]"]
  node_update["Release checker<br/>[update.ts]"]
end

subgraph group_editor["Editor runtime"]
  node_vscoderoute["VS Code routes<br/>[vscode.ts]"]
  node_socket["Editor socket<br/>[vscodeSocket.ts]"]
  node_code["VS Code server"]
  node_serviceworker["Browser service worker<br/>[serviceWorker.ts]"]
end

node_user(("Browser user"))

node_user -->|"opens IDE"| node_httpapp
node_entry -->|"parses options"| node_cli
node_entry -->|"starts server"| node_main
node_main -->|"creates server"| node_httpapp
node_main -->|"registers routes"| node_routes
node_httpapp -->|"handles upgrades"| node_wsrouter
node_wsrouter -.->|"dispatches sockets"| node_routes
node_routes -.->|"mounts auth"| node_login
node_routes -.->|"mounts checks"| node_health
node_routes -->|"mounts proxy"| node_domainproxy
node_routes -->|"dispatches paths"| node_pathproxy
node_routes -->|"mounts endpoint"| node_updateroute
node_routes -.->|"mounts editor"| node_vscoderoute
node_routes -.->|"uses security"| node_httphelpers
node_routes -->|"configures checker"| node_update
node_main -.->|"loads settings"| node_settings
node_vscoderoute -->|"delegates requests"| node_code
node_vscoderoute -->|"builds editor args"| node_cli
node_httpapp -->|"creates session service"| node_socket
node_user -.->|"loads client support"| node_serviceworker
node_httphelpers -->|"uses status types"| node_httpcommon

click node_cli "https://github.com/coder/code-server/blob/main/src/node/cli.ts"
click node_entry "https://github.com/coder/code-server/blob/main/src/node/entry.ts"
click node_main "https://github.com/coder/code-server/blob/main/src/node/main.ts"
click node_settings "https://github.com/coder/code-server/blob/main/src/node/settings.ts"
click node_httpapp "https://github.com/coder/code-server/blob/main/src/node/app.ts"
click node_httphelpers "https://github.com/coder/code-server/blob/main/src/node/http.ts"
click node_wsrouter "https://github.com/coder/code-server/blob/main/src/node/wsRouter.ts"
click node_routes "https://github.com/coder/code-server/blob/main/src/node/routes/index.ts"
click node_login "https://github.com/coder/code-server/blob/main/src/node/routes/login.ts"
click node_health "https://github.com/coder/code-server/blob/main/src/node/routes/health.ts"
click node_domainproxy "https://github.com/coder/code-server/blob/main/src/node/routes/domainProxy.ts"
click node_pathproxy "https://github.com/coder/code-server/blob/main/src/node/routes/pathProxy.ts"
click node_updateroute "https://github.com/coder/code-server/blob/main/src/node/routes/update.ts"
click node_update "https://github.com/coder/code-server/blob/main/src/node/update.ts"
click node_vscoderoute "https://github.com/coder/code-server/blob/main/src/node/routes/vscode.ts"
click node_socket "https://github.com/coder/code-server/blob/main/src/node/vscodeSocket.ts"
click node_code "https://github.com/coder/code-server/tree/main/lib/vscode"
click node_events "https://github.com/coder/code-server/blob/main/src/common/emitter.ts"
click node_httpcommon "https://github.com/coder/code-server/blob/main/src/common/http.ts"
click node_serviceworker "https://github.com/coder/code-server/blob/main/src/browser/serviceWorker.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_entry,node_main,node_settings,node_user toneBlue
class node_httpapp,node_httphelpers,node_wsrouter,node_events,node_httpcommon toneAmber
class node_routes,node_login,node_health,node_domainproxy,node_pathproxy,node_updateroute,node_update toneMint
class node_vscoderoute,node_socket,node_code,node_serviceworker toneRose
```

## Components

### Startup and configuration

- [CLI configuration](https://github.com/coder/code-server/blob/main/src/node/cli.ts): `src/node/cli.ts`
- [Process entry](https://github.com/coder/code-server/blob/main/src/node/entry.ts): `src/node/entry.ts`
- [Server lifecycle](https://github.com/coder/code-server/blob/main/src/node/main.ts): `src/node/main.ts`
- [Persistent settings](https://github.com/coder/code-server/blob/main/src/node/settings.ts): `src/node/settings.ts`

### HTTP and WebSocket

- [HTTP app server](https://github.com/coder/code-server/blob/main/src/node/app.ts): `src/node/app.ts`
- [HTTP security helpers](https://github.com/coder/code-server/blob/main/src/node/http.ts): `src/node/http.ts`
- [WebSocket dispatch](https://github.com/coder/code-server/blob/main/src/node/wsRouter.ts): `src/node/wsRouter.ts`
- [Event emitter](https://github.com/coder/code-server/blob/main/src/common/emitter.ts): `src/common/emitter.ts`
- [HTTP primitives](https://github.com/coder/code-server/blob/main/src/common/http.ts): `src/common/http.ts`

### Access and routing

- [Route registration](https://github.com/coder/code-server/blob/main/src/node/routes/index.ts): `src/node/routes/index.ts`
- [Login and logout](https://github.com/coder/code-server/blob/main/src/node/routes/login.ts): `src/node/routes/login.ts`
- [Health checks](https://github.com/coder/code-server/blob/main/src/node/routes/health.ts): `src/node/routes/health.ts`
- [Domain forwarding](https://github.com/coder/code-server/blob/main/src/node/routes/domainProxy.ts): `src/node/routes/domainProxy.ts`
- [Port forwarding](https://github.com/coder/code-server/blob/main/src/node/routes/pathProxy.ts): `src/node/routes/pathProxy.ts`
- [Update endpoint](https://github.com/coder/code-server/blob/main/src/node/routes/update.ts): `src/node/routes/update.ts`
- [Release checker](https://github.com/coder/code-server/blob/main/src/node/update.ts): `src/node/update.ts`

### Editor runtime

- [VS Code routes](https://github.com/coder/code-server/blob/main/src/node/routes/vscode.ts): `src/node/routes/vscode.ts`
- [Editor socket](https://github.com/coder/code-server/blob/main/src/node/vscodeSocket.ts): `src/node/vscodeSocket.ts`
- [VS Code server](https://github.com/coder/code-server/tree/main/lib/vscode): `lib/vscode`
- [Browser service worker](https://github.com/coder/code-server/blob/main/src/browser/serviceWorker.ts): `src/browser/serviceWorker.ts`

### Other components

- **Browser user**

## Connections

- Browser user → HTTP app server: opens IDE
- Process entry → CLI configuration: parses options (evidence: `src/node/entry.ts`)
- Process entry → Server lifecycle: starts server (evidence: `src/node/entry.ts`)
- Server lifecycle → HTTP app server: creates server (evidence: `src/node/main.ts`)
- Server lifecycle → Route registration: registers routes (evidence: `src/node/main.ts`)
- HTTP app server → WebSocket dispatch: handles upgrades (evidence: `src/node/app.ts`)
- WebSocket dispatch → Route registration: dispatches sockets (evidence: `src/node/routes/index.ts`)
- Route registration → Login and logout: mounts auth (evidence: `src/node/routes/index.ts`)
- Route registration → Health checks: mounts checks (evidence: `src/node/routes/index.ts`)
- Route registration → Domain forwarding: mounts proxy (evidence: `src/node/routes/index.ts`)
- Route registration → Port forwarding: dispatches paths (evidence: `src/node/routes/index.ts`)
- Route registration → Update endpoint: mounts endpoint (evidence: `src/node/routes/index.ts`)
- Route registration → VS Code routes: mounts editor (evidence: `src/node/routes/index.ts`)
- Route registration → HTTP security helpers: uses security (evidence: `src/node/routes/index.ts`)
- Route registration → Release checker: configures checker (evidence: `src/node/routes/index.ts`)
- Server lifecycle → Persistent settings: loads settings
- VS Code routes → VS Code server: delegates requests (evidence: `src/node/routes/vscode.ts`)
- VS Code routes → CLI configuration: builds editor args (evidence: `src/node/routes/vscode.ts`)
- HTTP app server → Editor socket: creates session service (evidence: `src/node/app.ts`)
- Browser user → Browser service worker: loads client support
- HTTP security helpers → HTTP primitives: uses status types (evidence: `src/node/http.ts`)
