This document provides a high-level introduction to code-server, its architecture, and major system components. For detailed information about specific subsystems, refer to the Architecture section (#2) and its child pages. For build and release processes, see #4. For installation and deployment methods, see #5.
code-server is a Node.js application that enables running Visual Studio Code in a web browser on any machine. It wraps Microsoft's VS Code and makes it accessible via HTTP/HTTPS, allowing developers to code from any device with a browser.
Key characteristics:
| Aspect | Description |
|---|---|
| Base | VS Code (integrated as Git submodule with patches) |
| Runtime | Node.js 22 |
| Entry Point | out/node/entry.js |
| License | MIT |
| Distribution | npm package, standalone binaries, system packages (deb/rpm), Docker images, Helm charts |
The primary value proposition is enabling consistent development environments across devices, utilizing cloud computing resources, and preserving battery life on portable devices by offloading intensive tasks to servers.
Sources: package.json1-153 docs/README.md1-83
code-server follows a three-layer architecture that separates concerns between application logic, VS Code integration, and build/release processes.
Layer 1 handles all runtime application logic including HTTP serving, authentication, configuration management, and proxying.
Layer 2 integrates VS Code as a Git submodule located at lib/vscode with custom patches applied using quilt to enable server-side operation.
Layer 3 manages the build pipeline and artifact generation for multiple distribution channels.
Sources: package.json38 package.json11-36 high-level diagrams
The following diagram maps natural language concepts to actual code entities in the codebase:
Sources: package.json38 package.json94-96 high-level diagrams
| Component | File Path | Purpose |
|---|---|---|
| entry.js | out/node/entry.js (compiled from src/node/entry.ts) | Main process entry point, orchestrates initialization |
| cli.ts | src/node/cli.ts | Parses CLI arguments, loads configuration from multiple sources |
| http.ts | src/node/http.ts | Creates Express application, registers middleware and routes |
| routes/ | src/node/routes/ | Individual route handlers (login, health, static, etc.) |
| proxy.ts | src/node/proxy.ts | Implements port forwarding via /proxy/ and /absproxy/ endpoints |
| settings.ts | src/node/settings.ts | Manages persistent settings storage in JSON files |
| update.ts | src/node/update.ts | Checks for code-server updates from GitHub releases |
| i18n.ts | src/node/i18n.ts | Handles internationalization and custom string loading |
Sources: Directory structure inferred from package.json and high-level diagrams
code-server implements a hierarchical configuration system with three sources in order of precedence:
| Mode | Description | Rate Limiting |
|---|---|---|
password | Password-based authentication using hashed passwords (argon2, SHA256, or plain text) | 2 attempts/minute + 12 attempts/hour |
none | No authentication required (use with caution) | N/A |
The password can be provided via:
PASSWORD environment variable (plain text or hashed)HASHED_PASSWORD environment variable (pre-hashed with argon2 or SHA256)password field in config.yamlconfig.yaml on first runSources: package.json70-89 CHANGELOG.md47-49 high-level diagrams
Rather than maintaining a full fork, code-server integrates VS Code as a Git submodule with modifications managed as quilt patches:
This approach enables:
Sources: package.json14 .gitignore23-25 high-level diagrams
code-server supports multiple deployment methods to accommodate different use cases:
| Format | Target Audience | Installation Method |
|---|---|---|
| npm package | Developers with Node.js | npm install -g code-server |
| Standalone | General users | Extracted to ~/.local, includes Node.js binary |
| System packages | Linux system administrators | apt install ./code-server*.deb or rpm -i code-server*.rpm |
| Docker images | Container deployments | docker run -it -p 8080:8080 codercom/code-server |
| Helm chart | Kubernetes deployments | helm install code-server ci/helm-chart |
The install.sh script automates installation by detecting the system and choosing the appropriate method:
Sources: install.sh1-619 install.sh264-296 install.sh349-448
For containerized deployments, code-server provides:
amd64 and arm64 architecturescodercom/code-server) and GHCRci/helm-chart/ with configurable valuesKey Helm chart configuration options:
| Parameter | Default | Description |
|---|---|---|
image.repository | codercom/code-server | Container image repository |
image.tag | 4.104.2 | code-server version |
service.type | ClusterIP | Kubernetes service type |
service.port | 8080 | Service port |
persistence.enabled | true | Enable persistent volume |
persistence.size | 10Gi | Persistent volume size |
extraArgs | [] | Additional CLI arguments |
extraVars | [] | Additional environment variables |
Sources: ci/helm-chart/values.yaml1-227 ci/helm-chart/Chart.yaml1-24 package.json30
The build process follows a multi-stage pipeline that produces artifacts for all distribution channels:
| Script | Purpose | Output |
|---|---|---|
ci/build/build-code-server.sh | Compile TypeScript to JavaScript | out/ directory |
ci/build/build-vscode.sh | Apply patches and build VS Code | lib/vscode/out-vscode/ |
ci/build/build-release.sh | Bundle into single Node module | release/ directory |
ci/build/build-standalone-release.sh | Create standalone with Node binary | release-standalone/ |
ci/build/build-packages.sh | Generate tar.gz, deb, rpm packages | release-packages/ |
Sources: package.json11-36 ci/README.md35-71
code-server employs a comprehensive testing strategy across multiple levels:
| Test Type | Framework | Command | Coverage |
|---|---|---|---|
| Unit tests | Jest | npm run test:unit | TypeScript source code, 60% line coverage minimum |
| Integration tests | Jest | npm run test:integration | Cross-module interactions |
| End-to-end tests | Playwright | npm run test:e2e | Full browser automation testing |
| Native module tests | Jest | npm run test:native | Native dependencies (argon2, etc.) |
| Shell script tests | Custom | npm run test:scripts | Build and CI scripts |
Sources: package.json19-34 package.json109-152 ci/README.md13-33
Key production dependencies include:
| Package | Purpose |
|---|---|
express (v5.0.1) | HTTP server framework |
argon2 (v0.31.1) | Password hashing for authentication |
http-proxy (v1.18.1) | Port forwarding proxy implementation |
compression (v1.7.4) | HTTP response compression |
ws (v8.14.2) | WebSocket support |
cookie-parser (v1.4.6) | Cookie handling for sessions |
limiter (v2.1.0) | Rate limiting for authentication |
pem (v1.14.8) | TLS certificate generation |
i18next (v25.3.0) | Internationalization support |
js-yaml (v4.1.0) | YAML config file parsing |
| Package | Purpose |
|---|---|
typescript (v5.6.2) | TypeScript compiler |
eslint (v9.12.0) | Code linting |
prettier (v3.6.2) | Code formatting |
ts-node (v10.9.1) | TypeScript execution for dev scripts |
Sources: package.json70-90 package.json39-69
| Requirement | Specification |
|---|---|
| Node.js | Version 22 (specified in engines) |
| Operating System | Linux (primary), macOS, FreeBSD |
| Architecture | amd64 (x86_64), arm64 |
| Minimum RAM | 1 GB |
| Minimum CPU | 2 cores |
| WebSockets | Must be enabled |
| glibc | 2.28+ (for Node 18+) |
Sources: package.json106-108 docs/requirements.md1-57 CHANGELOG.md614-619
code-server version numbering follows the pattern 4.x.y where the 4 indicates the major version of code-server, and the bundled VS Code version is tracked separately. As of the current codebase snapshot:
--cookie-suffix flag for cookie customizationauthorizationHeaderToken support for extension gallery authenticationRelease artifacts are published to:
code-server packagecodercom/code-serverSources: CHANGELOG.md1-1253 package.json2-10
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.