Self-Hosting OpenVSCode Server with Docker

What Is OpenVSCode Server?

OpenVSCode Server runs VS Code on a remote server and serves it through your browser. It’s built by Gitpod — the same company behind the cloud IDE — and it’s the actual VS Code codebase (not a fork), so you get full extension compatibility with the official VS Code marketplace. This means every extension you use in desktop VS Code works here. It replaces GitHub Codespaces and Gitpod’s cloud offering with a self-hosted solution on your own hardware.

Official site: github.com/gitpod-io/openvscode-server

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 1 GB of free RAM minimum (2 GB recommended for large projects)
• A domain name (recommended for HTTPS access)

Docker Compose Configuration

Create a directory for your workspace:

mkdir -p /opt/openvscode-server/workspace

Create a docker-compose.yml file:

# /opt/openvscode-server/docker-compose.yml
services:
  openvscode:
    image: gitpod/openvscode-server:1.109.5
    container_name: openvscode-server
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./workspace:/home/workspace:cached    # Your code projects
      - vscode-data:/home/.openvscode-server  # Extensions, settings, state
    environment:
      - CONNECTION_TOKEN=${CONNECTION_TOKEN}   # Authentication token
    user: "1000:1000"  # Match your host user UID:GID

volumes:
  vscode-data:

Create a .env file with an authentication token:

# Generate a random token
echo "CONNECTION_TOKEN=$(openssl rand -hex 24)" > .env

Start the server:

docker compose up -d

Access VS Code at http://your-server-ip:3000/?tkn=YOUR_TOKEN (replace with your actual token).

Authentication

OpenVSCode Server uses a connection token for authentication. Without a token, anyone who can reach port 3000 has full access to your code and terminal.

Option 1: Token authentication (default)

Set CONNECTION_TOKEN in your environment. Access the server with ?tkn=YOUR_TOKEN in the URL. The browser remembers the token after the first visit.

Option 2: Disable authentication (behind reverse proxy only)

If you’re using a reverse proxy with its own authentication (Authelia, Authentik, HTTP basic auth):

environment:
  - CONNECTION_TOKEN=none    # Disables built-in auth

Only do this behind a reverse proxy with authentication. Never expose an unauthenticated instance to the internet.

Reverse Proxy

For HTTPS access with a custom domain:

Caddy:

code.example.com {
    reverse_proxy openvscode:3000
}

Nginx Proxy Manager: Add a proxy host pointing to openvscode:3000. Enable WebSocket support — VS Code requires it for the terminal and live features.

See Reverse Proxy Setup and Caddy Setup.

Installing Extensions

Extensions install the same way as desktop VS Code:

1. Open the Extensions sidebar (Ctrl+Shift+X)
2. Search for extensions
3. Click Install

Extensions persist in the vscode-data volume. They survive container restarts and upgrades.

OpenVSCode Server connects to the official VS Code marketplace (Open VSX is not needed), so nearly every extension is available.

Multiple Workspaces

Mount additional directories as workspace folders:

volumes:
  - ./workspace:/home/workspace:cached
  - /home/user/projects:/home/projects:cached
  - /opt/repos:/home/repos:cached

Switch between folders using File → Open Folder in the VS Code interface.

Git Integration

Git works out of the box inside the container. Configure your identity:

# Inside the VS Code terminal
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

For SSH key access to private repos, mount your SSH keys:

volumes:
  - ~/.ssh:/home/.ssh:ro

Backup

Back up two things:

1. Your workspace files — whatever’s in the mounted workspace directory
2. VS Code settings and extensions — the vscode-data named volume

# Backup the named volume
docker run --rm -v openvscode-server_vscode-data:/data -v $(pwd):/backup alpine tar czf /backup/vscode-data-backup.tar.gz /data

See Backup Strategy.

Troubleshooting

WebSocket connection failed

Symptom: Terminal doesn’t open, extensions fail to load, “WebSocket close with status code 1006” in browser console. Fix: Your reverse proxy must support WebSocket upgrades. In Nginx, add proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade";. Nginx Proxy Manager enables this automatically when you check “WebSocket Support.”

Permission denied on workspace files

Symptom: Can’t create or edit files in the workspace directory. Fix: The container runs as UID 1000 by default. Ensure your workspace directory is owned by UID 1000: chown -R 1000:1000 /opt/openvscode-server/workspace.

Extensions not installing

Symptom: Extensions fail to download or install. Fix: The container needs internet access to reach the VS Code marketplace. Check that your Docker network allows outbound HTTPS. If behind a corporate proxy, set HTTP_PROXY and HTTPS_PROXY environment variables.

Resource Requirements

• RAM: 512 MB idle, 1–2 GB with a large project open
• CPU: Low idle, moderate during builds/compilation
• Disk: ~500 MB for the container image, plus workspace and extension storage

Verdict

OpenVSCode Server is the best way to run VS Code in a browser. It’s the actual VS Code (not a fork), built by Gitpod, with full marketplace access. code-server is the alternative — it’s more mature and has more configuration options, but uses the Open VSX marketplace instead of the official one. If extension compatibility matters most, choose OpenVSCode Server. If you want more server-side configuration and don’t mind Open VSX, code-server is equally solid.

Related

• How to Self-Host code-server
• code-server vs OpenVSCode Server
• Best Self-Hosted Development Tools
• Best Self-Hosted Git Hosting
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy