OpenCode Server Connection Fix: Desktop & Web

If OpenCode desktop or web shows “cannot connect to the server,� the cause is almost always a blocked port, a wrong server address, or a firewall rule. This guide walks you through the exact steps to diagnose and fix the connection on both the desktop app and the browser version.

Background: Why OpenCode Needs a Server

OpenCode is a code editing tool that runs a local server to handle file operations, language services, and extensions. The desktop app starts this server automatically; the web version connects to a server you specify (often the same local one). When the server isn’t reachable, you see the connection error. Common reasons include:

• The server process crashed or didn’t start.
• Another program is using the same port (default 3000).
• Your firewall or antivirus is blocking the connection.
• The server address or port in settings is wrong.
• You’re on a VPN or network that restricts local connections.

How the Connection Works

OpenCode’s desktop app launches a Node.js server on localhost (127.0.0.1) at a specific port, usually 3000. The web version connects to that same address over HTTP. The browser or app sends a request to http://127.0.0.1:3000; if the server responds, the editor loads. If not, you get the error. The web version can also connect to a remote server if you’ve configured one, but the default is local.

Step-by-Step Fix for Desktop

1. Check if the server is running. Open a terminal and run curl http://127.0.0.1:3000 (or your configured port). If you get a response, the server is up; if not, it’s down.
2. Restart OpenCode completely. Quit the app (not just close the window) and relaunch it. This restarts the server.
3. Kill any leftover processes. On Windows, open Task Manager and end any “node.exe� processes. On Mac/Linux, run pkill node in the terminal. Then relaunch OpenCode.
4. Change the port. If port 3000 is occupied, change the port in OpenCode’s settings (usually under “Server� or “Port�). Try 3001 or 8080. Update the server address accordingly.
5. Check firewall/antivirus. Temporarily disable your firewall or add an exception for OpenCode and Node.js. If the error disappears, re-enable and add a permanent rule.
6. Reinstall if necessary. As a last resort, uninstall and reinstall OpenCode. This resets all settings and clears any corrupted files.

Step-by-Step Fix for Web

1. Verify the server address. In the web app, check the “Server URL� field. It should be http://127.0.0.1:3000 (or the port you set). A typo here is a common cause.
2. Make sure the desktop server is running. The web version doesn’t start the server itself; it connects to one. Launch the desktop app first, then try the web version.
3. Use the correct host. If you’re accessing from another device, use the computer’s LAN IP (e.g., http://192.168.1.10:3000) instead of localhost. Ensure the server is bound to 0.0.0.0 in settings.
4. Clear browser cache. Sometimes the browser caches a failed connection. Hard-refresh (Ctrl+F5) or clear cache for the site.
5. Try a different browser. If it still fails, test in another browser to rule out extensions or browser settings.

Common Problems and Specific Fixes

• Port already in use: Run netstat -ano | findstr :3000 (Windows) or lsof -i :3000 (Mac/Linux) to see what’s using the port. Then either stop that process or change OpenCode’s port.
• VPN interference: VPNs can block localhost connections. Disconnect from the VPN and try again.
• Proxy settings: If you have a system proxy, add 127.0.0.1 to the “no proxy� list.
• Antivirus false positive: Some antivirus software flags Node.js as suspicious. Add an exclusion for the OpenCode installation folder.
• Corrupted user data: Delete the OpenCode configuration folder (location varies by OS) to reset settings. Back up any important projects first.

How to Choose the Right Fix

Start with the simplest: restart the app. If that fails, check if the server is actually running via curl. If it’s not, kill node processes and relaunch. If it is running but you still get the error, the problem is likely the address or firewall. For web, always confirm the desktop server is up first. If you’re using a remote server, verify the IP and port are reachable from your network.

Comparison: Desktop vs. Web

The desktop app manages the server lifecycle automatically, so most issues are local (port conflicts, crashes). The web version is more flexible (can connect to remote servers) but depends on the server being already started and reachable. Desktop is more reliable for local work; web is better for remote development. If you switch between them, make sure the server settings match.

Safety and Precautions

When changing firewall rules or disabling security software, be cautious. Only add exceptions for programs you trust. When using a remote server, ensure it’s on a secure network and use authentication if available. Never expose your OpenCode server to the public internet without a strong password or SSH tunnel.

Frequently Asked Questions

Why does OpenCode say “cannot connect to the server� even though the app is open?

The app window being open doesn’t mean the server process is running. It may have crashed or been killed. Check with curl or restart the app.

What port does OpenCode use by default?

The default is port 3000, but you can change it in settings. If you change it, update the server URL in both desktop and web.

Can I use OpenCode web without installing the desktop app?

Yes, but you need to have a server running somewhere—either on your machine (by installing the server component) or on a remote machine. The web app alone doesn’t include a server.

Why does the web version work on my phone but not on my computer?

If the server is running on your computer, your phone and computer should both be able to connect via LAN IP. If it only works on one, check the firewall on the computer and ensure the server is bound to 0.0.0.0.

Will changing the port affect my projects?

No, your projects are stored on disk and are independent of the port. Changing the port only affects how you connect to the server.

Related

• Where Do Screenshots Go? Saved Locations Explained
• Fix Jetpack Cannot Connect Site Inaccessible Error
• Choose a Text Message AI Agent: Privacy, Tasks & Cost