tutorial

How to Monitor VS Code Server (Self-Hosted) with Vigilmon

VS Code Server lets you run VS Code in the browser, backed by a remote Linux machine. When your team relies on a self-hosted VS Code Server instance — for re...

VS Code Server lets you run VS Code in the browser, backed by a remote Linux machine. When your team relies on a self-hosted VS Code Server instance — for remote development, pair programming, or a standardized development environment — uptime becomes a real concern. If the server goes down and no one notices, developers lose access to their work mid-session.

In this tutorial you'll set up external uptime monitoring for your self-hosted VS Code Server using Vigilmon — free tier, no credit card required.

Why self-hosted VS Code Server needs external monitoring

VS Code Server runs as a long-lived process on a Linux host. Unlike a web app where crashes are obvious, VS Code Server failures can be subtle:

  • Process crash without restart — if your systemd unit or supervisor config has a restart limit, a crashing server eventually stays down. The host is up; VS Code is not
  • Port binding failure — after a server reboot, VS Code Server may fail to bind to its port if the previous process didn't clean up its socket
  • Proxy or reverse proxy misconfiguration — teams often put VS Code Server behind nginx or Caddy. A configuration update can break the proxy while leaving the VS Code process running
  • TLS certificate expiry — self-managed certificates expire. When they do, browsers refuse the connection but the process is still running, so local health checks look fine
  • Resource exhaustion — a developer's environment consuming too much RAM can make VS Code Server unresponsive without fully crashing
  • Token authentication failures — VS Code Server uses connection tokens; if the token rotates unexpectedly, all browser sessions disconnect

External monitoring from Vigilmon catches all of these because it checks the service from outside your network, the same way a developer's browser would.

What you'll need

  • A Linux host running VS Code Server (from code-server package or the official code CLI with --remote support)
  • The server accessible via a domain name or public IP
  • A free Vigilmon account (sign up takes 30 seconds)

Step 1: Set up VS Code Server with a health-checkable endpoint

The most common self-hosted setup uses code-server (the open-source distribution by Coder) or Microsoft's code CLI in tunnel/server mode. Here's how to set up code-server with systemd:

# Install code-server
curl -fsSL https://code-server.dev/install.sh | sh

# Enable and start the service
sudo systemctl enable --now code-server@$USER

By default, code-server listens on http://127.0.0.1:8080. Configure it in ~/.config/code-server/config.yaml:

# ~/.config/code-server/config.yaml
bind-addr: 0.0.0.0:8080
auth: password
password: your-secure-password
cert: false

Put it behind a reverse proxy

For production use, always put code-server behind nginx or Caddy with TLS. Here's an nginx config:

# /etc/nginx/sites-available/code-server
server {
    listen 443 ssl http2;
    server_name code.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/code.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/code.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection upgrade;
        proxy_set_header Accept-Encoding gzip;
    }
}

Enable and reload:

sudo ln -s /etc/nginx/sites-available/code-server /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Add a dedicated health check endpoint

code-server doesn't have a built-in /health endpoint, but it does return HTTP 200 on its root path when running correctly. You can also add a simple health script:

# /usr/local/bin/code-server-health
#!/bin/bash
# Returns 0 if code-server is healthy, 1 if not
curl -sf -o /dev/null http://127.0.0.1:8080 && echo "healthy" || echo "unhealthy"

For Vigilmon, use the root path (/) or a known path that returns 200. Verify it:

curl -I https://code.yourdomain.com/
# HTTP/2 200
# content-type: text/html; charset=utf-8

Note: code-server returns 200 on / when the password page loads. Even if developers need to log in, the 200 response confirms the server is up and the proxy is working.

Step 2: Set up HTTP monitoring in Vigilmon

Add your VS Code Server URL to Vigilmon:

  1. Log in to vigilmon.online and go to Monitors → New Monitor
  2. Choose HTTP / HTTPS as the monitor type
  3. Set the URL to https://code.yourdomain.com
  4. Set the check interval to 1 minute
  5. Under Expected response:
    • Status code: 200
    • (Optional) Response body contains: VS Code — the login page includes this in the title
  6. Save the monitor

Vigilmon probes this URL from multiple geographic regions. When the server goes down — whether from a process crash, proxy failure, or certificate expiry — Vigilmon detects it immediately.

Separate monitors for separate instances

If your team runs multiple VS Code Server instances (one per developer, or per project), create a monitor for each:

| Instance | URL | Monitor Name | |----------|-----|--------------| | Team shared | https://code.yourdomain.com | vscode-server/team | | Dev 1 | https://dev1-code.yourdomain.com | vscode-server/dev1 | | Project A | https://project-a-code.yourdomain.com | vscode-server/project-a |

Step 3: Monitor the TCP layer

HTTP monitoring catches application-level failures. TCP monitoring catches lower-level issues — the port not being open at all — which can happen when the process crashes and the socket isn't cleaned up properly.

Add a TCP monitor for your VS Code Server port:

  1. In Vigilmon, go to Monitors → New Monitor
  2. Choose TCP Port
  3. Enter host: code.yourdomain.com, port: 443 (or 8080 if direct)
  4. Save the monitor

If the TCP monitor fails while the HTTP monitor reports the host is reachable, you have an nginx or Caddy misconfiguration rather than a VS Code Server process failure. This distinction speeds up diagnosis significantly.

Step 4: Configure alert channels

When developers lose access to VS Code Server mid-session, they need to know it's a known outage — not a bug with their own connection.

Email alerts

  1. In Vigilmon, go to Alert Channels → Add Channel → Email
  2. Add your DevOps or infrastructure email
  3. Assign the channel to your VS Code Server monitors

Slack webhook alerts

  1. Go to Alert Channels → Add Channel → Webhook
  2. Enter your Slack webhook URL
  3. Assign the channel to your monitors

Vigilmon sends this payload on downtime:

{
  "monitor_name": "vscode-server/team",
  "status": "down",
  "url": "https://code.yourdomain.com",
  "started_at": "2024-01-15T10:23:00Z",
  "duration_seconds": 300
}

Use this to trigger automatic recovery actions. A webhook handler for VS Code Server restart:

#!/bin/bash
# restart-code-server.sh — triggered by Vigilmon webhook
sudo systemctl restart code-server@dev

# Wait and verify
sleep 5
if systemctl is-active --quiet code-server@dev; then
  echo "code-server restarted successfully"
else
  echo "code-server restart failed — escalating"
  # Send PagerDuty or email alert here
fi

Diagnosing VS Code Server failures

When Vigilmon alerts you that VS Code Server is down:

# Check the systemd unit status
sudo systemctl status code-server@$USER

# Check the last 50 lines of logs
sudo journalctl -u code-server@$USER -n 50

# Check nginx status and error log
sudo systemctl status nginx
sudo tail -20 /var/log/nginx/error.log

# Check if the port is bound
sudo ss -tlnp | grep 8080

# Test the direct connection (bypassing nginx)
curl -v http://127.0.0.1:8080

# Check TLS certificate expiry
openssl s_client -connect code.yourdomain.com:443 -servername code.yourdomain.com \
  < /dev/null 2>/dev/null | openssl x509 -noout -dates

If systemd shows the service as inactive, restart it:

sudo systemctl restart code-server@$USER

If the service is active but not responding on port 8080, check for a port conflict:

sudo fuser 8080/tcp

Step 5: TLS certificate monitoring

Self-hosted VS Code Server almost always uses Let's Encrypt via Certbot or Caddy's automatic HTTPS. Both can fail silently:

  • Certbot fails if the HTTP challenge is blocked (firewall rule, nginx config change)
  • Caddy's ACME renewal fails if DNS is misconfigured or rate limits are hit

Vigilmon automatically monitors TLS certificate expiry when you set up an HTTPS monitor. You'll receive alerts:

  • 30 days before expiry — time to investigate why auto-renewal failed
  • 7 days before expiry — urgent
  • On expiry — the monitor will show failures as browsers reject the connection

Check your Certbot renewal status proactively:

sudo certbot renew --dry-run
sudo systemctl status certbot.timer

Step 6: Automate VS Code Server health with systemd watchdog

To complement external Vigilmon monitoring, configure systemd to automatically restart code-server on failure:

# /etc/systemd/system/code-server@.service.d/restart.conf
[Service]
Restart=always
RestartSec=10
StartLimitIntervalSec=200
StartLimitBurst=5

Reload systemd to apply:

sudo systemctl daemon-reload

This handles process crashes automatically. Vigilmon then catches everything systemd can't — external routing failures, certificate issues, proxy misconfigurations.

Step 7: Create a status page

If multiple developers depend on a shared VS Code Server instance, give them a status page so they can self-diagnose connectivity issues:

  1. In Vigilmon, go to Status Pages → New Status Page
  2. Name it: "Development Infrastructure"
  3. Add your VS Code Server monitors
  4. Optionally add other development tools: GitLab, Gitea, internal package registries
  5. Publish the page and share the URL in your team's README

Putting it all together

Here's the recommended monitoring setup for a self-hosted VS Code Server:

| Monitor | Type | What it catches | |---------|------|-----------------| | https://code.yourdomain.com | HTTP | Process crashes, proxy failures, auth issues | | code.yourdomain.com:443 | TCP | Port binding failures, TLS connectivity | | TLS certificate (automatic) | SSL | Certificate expiry, renewal failures |

What's next

  • Heartbeat monitoring — if you run scripts or build tasks inside VS Code Server, use Vigilmon's heartbeat monitors to alert you if they stop executing on schedule
  • Multi-region testing — Vigilmon's multi-region probes catch geographic routing issues, such as when your VS Code Server is reachable from Europe but not from Asia
  • Uptime SLAs — Vigilmon's uptime reports give you monthly availability percentages, useful for tracking infrastructure reliability over time

Get started free at vigilmon.online — no credit card, monitors start running in under a minute.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles