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 "you@example.com"

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.

Frequently Asked Questions

What’s the difference between OpenVSCode Server and code-server?

Both run VS Code in a browser, but they come from different teams. OpenVSCode Server is built by Gitpod and uses the official VS Code Marketplace — every extension available in desktop VS Code works. code-server is built by Coder and uses the Open VSX marketplace, which has fewer extensions. code-server offers more server-side configuration options (built-in auth, proxy support). Choose OpenVSCode Server for maximum extension compatibility; choose code-server for more built-in server features.

Is OpenVSCode Server secure enough for remote development?

OpenVSCode Server has no built-in authentication — anyone with network access can use it. Always run it behind a reverse proxy with authentication (Authelia, Authentik, or basic auth in Nginx Proxy Manager) and HTTPS. Never expose port 3000 directly to the internet. Additionally, connection tokens can be configured for basic protection.

Can I use OpenVSCode Server as a team IDE?

Each OpenVSCode Server instance serves one workspace. For multi-user setups, run separate containers per developer (different ports, separate workspace directories). There’s no built-in multi-user support or user isolation. For team cloud IDEs, consider Gitpod (the commercial product from the same company) or JupyterHub for notebook-based development.

Does OpenVSCode Server support terminal access?

Yes. The integrated terminal works identically to desktop VS Code — full bash/zsh access within the container. You can install additional tools, compilers, and runtimes inside the container. Mount additional volumes for access to host resources. The terminal runs as the container’s user (UID 1000 by default).

How much RAM does OpenVSCode Server need?

The server itself uses ~300-500 MB. Memory usage scales with the project size, open files, and active extensions. A large TypeScript project with IntelliSense can use 1-2 GB. Language servers (Python, Java, Go) each add 200-500 MB. For comfortable development, allocate 2 GB minimum, 4 GB for larger projects.

Can I use my existing VS Code settings and extensions?

Settings sync is not built in, but you can mount a local settings directory into the container. Extensions install from the VS Code Marketplace through the editor UI or via the command line with code --install-extension. Your installed extensions persist in the workspace volume across container restarts.

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