Overview

Relevant source files

• CHANGELOG.md
• ci/helm-chart/Chart.yaml
• ci/helm-chart/values.yaml
• docs/FAQ.md
• docs/README.md
• docs/collaboration.md
• docs/guide.md
• docs/helm.md
• docs/ipad.md
• docs/manifest.json
• docs/requirements.md
• docs/triage.md
• package-lock.json
• package.json
• src/node/settings.ts
• test/unit/node/settings.test.ts

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 and its child pages.

What is code-server

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 24
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-152 package.json106-107 docs/README.md1-82

Core Architecture

code-server follows a three-layer architecture that separates concerns between application logic, VS Code integration, and build/release processes.

High-Level System Layers

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.json11-36 package.json37 package.json94

Key Runtime Components

The following diagram maps natural language concepts to actual code entities in the codebase:

Runtime Component Architecture

Sources: package.json37 package.json69-89 package.json93-95

Component Descriptions

Component	File Path	Purpose
entry.js	out/node/entry.js	Main process entry point, orchestrates initialization.
cli.ts	src/node/cli.ts	Parses CLI arguments and loads configuration.
http.ts	src/node/http.ts	Creates Express application, registers middleware and routes.
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.

Sources: package.json37 package.json94 docs/FAQ.md23-25 docs/FAQ.md63-87

Configuration and Authentication

code-server implements a hierarchical configuration system with three sources in order of precedence:

Authentication Modes

Mode	Description	Rate Limiting
password	Password-based authentication using hashed passwords (argon2).	2 attempts/minute + 12 attempts/hour
none	No authentication required (use with caution).	N/A

Sources: package.json70 docs/FAQ.md63-84 docs/guide.md41-49

VS Code Integration Strategy

Rather than maintaining a full fork, code-server integrates VS Code as a Git submodule with modifications managed as quilt patches. This approach enables tracking upstream VS Code releases while maintaining custom logic for:

• Custom authentication replacing VS Code's built-in auth.
• Sub-path hosting for reverse proxies.
• Built-in port forwarding proxy via src/node/proxy.ts.
• Custom extension marketplaces (Open-VSX by default).

Sources: package.json14 docs/FAQ.md106-127 docs/collaboration.md22-25

Distribution and Deployment

Distribution Formats

Format	Target Audience	Installation Method
npm package	Developers with Node.js	npm install -g code-server
Docker images	Container deployments	docker run -it -p 8080:8080 codercom/code-server
Helm chart	Kubernetes deployments	helm upgrade --install code-server ci/helm-chart

Sources: package.json16-35 docs/README.md29-52 docs/helm.md12-16

Helm Chart Configuration

The Helm chart located at ci/helm-chart/ provides a production-ready deployment for Kubernetes.

Parameter	Default	Description
image.repository	codercom/code-server	Container image repository.
image.tag	4.135.0	code-server version.
service.port	8080	Port for the code-server service.
persistence.enabled	true	Enable persistent volume for user data.

Sources: ci/helm-chart/values.yaml7-10 ci/helm-chart/values.yaml48-50 ci/helm-chart/values.yaml131-132 ci/helm-chart/Chart.yaml23

Build and Testing

Build Pipeline

The build process is orchestrated via npm scripts that call specialized shell scripts:

• npm run build: Builds code-server components.
• npm run build:vscode: Builds the integrated VS Code submodule.
• npm run release: Packages the application for release.

Sources: package.json11-17

Testing Infrastructure

• Unit tests: Jest-based tests for Node.js logic.
• E2E tests: Playwright-based tests for browser interaction.
• Integration tests: Validates component interactions.

Sources: package.json18-23 package.json108-151