Skip to main content

Secure Browser Access to code-server VSCode Behind Pomerium

In this guide, you'll run code-server's Visual Studio Code (VSCode) in a Docker container, and secure browser access to your project with Pomerium.

What is code-server?

Code-server is an open-source tool that allows you to run VSCode, a popular integrated development environment (IDE), on a remote server through the browser. This setup essentially turns VSCode into a cloud-based IDE, providing flexibility and accessibility advantages.

Code-server is particularly popular among developers who want the full power of VSCode, but need to work in a cloud-based environment. This is ideal if you work on multiple machines, need to access your development environment remotely, or you have limited local resources.

How to secure code-server with Pomerium

Code-server requires password authentication by default. By securing code-server behind Pomerium, you can remove code-server’s password requirement and configure Pomerium to add authentication and authorization to an online instance of VSCode.

This guide shows you how to secure code-server with Pomerium. Here are the steps you’ll follow:

  1. Install code-server and run it in a Docker container

  2. Access your code-server project in the browser listening on localhost

  3. Configure Pomerium to safely expose your code-server instance

By the end, you will have a minimal, real-world code-server instance that allows developer teams to write code using VSCode in the browser.

A code-server VSCode project running in the browser behind Pomerium.

Before you start

If you completed our Quickstart guide, you should have a working Pomerium project with the following YAML files:

  • config.yaml
  • docker-compose.yaml

If you haven't completed the Quickstart:

  • Install Docker and Docker Compose
  • Create a config.yaml file for your Pomerium configuration
  • Create a docker-compose.yaml file for your Docker configuration

Set up Pomerium

In your config.yaml file, add our hosted authenticate service URL:


Add the following route:

- from:
to: http://codeserver:8080
- allow:
- email:
allow_any_authenticated_user: true
allow_websockets: true

In this example route, is the publicly accessible route. codeserver is the local hostname for the server or container running code-server.

Set up Docker Compose

In your docker-compose.yaml file, add the code-server and Pomerium services:

version: '3'
- ./config.yaml:/pomerium/config.yaml:ro
- 443:443
image: codercom/code-server:latest
- 8080:8080
- ./code-server:/home/coder/project
- ./code-server-config/.config:/home/coder/.config

Access code-server on localhost

Run docker compose up. In your browser, go to localhost:8080.

Code-server will prompt you to enter a password:

Code-server password prompt requiring a generated password found in the code-server config file

You can find a pre-generated password in code-server-config/.config/code-server/config.yaml. If you enter it, you gain access to your code-server project.

However, remembering passwords is tedious. Let's disable the password requirement and use Pomerium to enforce authentication and authorization instead.

Access code-server behind Pomerium

In docker-compose.yaml, add the following command to your code-server container:

image: codercom/code-server:latest
- 8080:8080
- ./code-server:/home/coder/project
- ./code-server-config/.config:/home/coder/.config
command: --auth none --disable-telemetry /home/coder/project

This will disable the password prompt (and prevent code-server from collecting telemetry data from your project). Now, restart Docker Compose and access code-server using the route defined in config.yaml:

After authenticating against the Cognito identity provider, you will be redirected to the code-server route.

A VSCode project running “Hello World” in the integrated terminal.

Build a project in code-server

Now that you can access VSCode in your browser, test out code-server by building a quick HTML project.

  1. Create an index.html file and add the following code:
<!DOCTYPE html>
<html lang="en">
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Code-Server Sample</title>
<h1 style="color:blueviolet">Check out more from Pomerium:</h1>
<ul style="font-size: 20px;">
<li><a href="">Guides</a></li>
<li><a href="">Blog</a></li>
<li><a href="">Documentation</a></li>
<h2 style="color:blueviolet">Happy coding!</h2>
  1. Go to Extensions and install Live Server
  2. Right-click index.html and select Open with Live Server
  3. Select any of the links to learn more about Pomerium

Great job! You successfully deployed code-server.


When the code-server container is rebuilt, any files outside of /home/coder/project are reset, removing any dependencies (such as go and make). In a real remote development workflow, you could mount additional volumes, or use a custom code-server container with these dependencies installed.