OpenCode uses a client/server architecture rather than three completely separate applications. The terminal interface (TUI), browser interface and Desktop app are clients that send requests to an OpenCode server. That server exposes an HTTP API and an OpenAPI 3.1 description, so the important question is always which server process and URL a client is using.
Terminal and web can deliberately share sessions: run opencode web, then connect the TUI with opencode attach <server-url>. Desktop normally starts its own local server sidecar, although it can be configured to use another server URL. A separately launched web or headless server is not automatically the backend used by Desktop.
As an Amazon Associate I earn from qualifying purchases.
The shared-service model in one sentence
Every OpenCode interface is a client of a particular backend process. The backend owns the running sessions and exposes HTTP endpoints; the client supplies the user interface. OpenCode’s server documentation describes this relationship directly: “Where the TUI is the client that talks to the server.” The server API and its OpenAPI 3.1 specification are documented in the OpenCode server documentation.
Recommended Free Tools
This distinction explains both the useful sharing behavior and the common surprises. Two clients pointed at the same server URL can see the same sessions and state. Two clients pointed at different server processes can have separate state even when they run on the same computer. “Shared service” therefore means shared backend, not a cloud account that synchronizes every installation automatically.
What the server actually does
The server is the process that accepts API requests, maintains OpenCode sessions and provides the data consumed by the terminal, browser and Desktop clients. A client does not need to know how another client is rendered; it only needs a reachable server URL and any required authentication.
- HTTP API: Clients communicate with HTTP endpoints exposed by the server.
- OpenAPI 3.1: The documented API description gives client developers a machine-readable contract for those endpoints.
- Session ownership: The server process holds the sessions that clients observe. Connecting to another process means connecting to another session store.
- Process boundaries: Starting a second server does not merge it with the first one. It creates another backend unless clients are explicitly directed to the same process.
The practical rule is simple: identify the server URL first, then decide which interfaces should connect to it.
How the terminal interface connects
Running opencode starts the terminal user interface (TUI) together with a server. The TUI acts as a client of that server rather than being the backend itself. For a normal local workflow, you launch the command, work in the terminal, and let the accompanying server handle the session requests.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchYou can also start a standalone headless server with opencode serve. The CLI reference distinguishes this from opencode web: serve provides API access without the browser interface, while web starts the browser experience as well.
If a server is already running, the TUI can attach to it instead of creating or using a different backend. The attachment command takes the server URL:
opencode attach <server-url>For example, if a local web server reports a URL such as http://127.0.0.1:4096, use that complete URL with opencode attach. The URL, including its port, is the identity of the backend from the TUI’s point of view.
How opencode web shares sessions with the TUI
opencode web starts a local OpenCode server and opens the browser interface. The web guide documents options for choosing a port or hostname, enabling mDNS discovery, allowing browser origins with CORS, and protecting the service with a password. By default, the command binds to 127.0.0.1 and chooses an available port.
To use the same sessions in a browser and terminal, follow this sequence:
- Start the web service. Run
opencode web. Let it open the browser, or copy the server URL it displays. - Record the exact URL. Keep the hostname and port together. A different port usually means a different server process.
- Attach the TUI. In another terminal, run
opencode attach <server-url>with the URL from the running web service. - Use either interface. The browser and TUI now address that same backend, so they can work with the same sessions and state.
This is intentional sharing, not automatic discovery between arbitrary processes. If you close the web-started server and launch a plain opencode command, the new TUI may start or select another server and will not necessarily show the sessions from the previous process.
The web guide also explains that binding to 0.0.0.0 makes the service reachable on the network. That changes the security requirements; it is not needed for a browser and TUI running on the same machine.
Rank #3
Desktop’s default is a local sidecar
OpenCode Desktop has a different default startup path. Its troubleshooting documentation describes a local opencode-cli server sidecar running in the background. Desktop uses that sidecar unless the installation is configured to connect to another server URL.
That means a Desktop window does not automatically join a server started by opencode web. To determine which backend Desktop is using, inspect the selected server URL and the app’s server configuration. If Desktop is pointed at the same URL as the web service, it can use that backend; if it is left on its default local sidecar, it is using a separate process and its own state.
When Desktop cannot connect, the troubleshooting guide recommends checking the selected URL and the server’s configuration or environment. A URL that works in a browser on one machine may not work from Desktop if the app is running in another environment, behind a firewall, or outside the network namespace where that address exists.
Comparing the main startup arrangements
| Startup method | Primary interface | Typical server behavior | How another client shares it | Default network detail |
|---|---|---|---|---|
opencode |
Terminal TUI | The TUI starts and uses a server | Attach another client to the server URL when it is available | Local behavior follows the installed release’s server settings |
opencode serve |
Headless HTTP API | Standalone server without the browser UI | Point a compatible client at its URL | Port 4096 and hostname 127.0.0.1 are documented defaults |
opencode web |
Browser web UI | Starts a server and opens the web interface | Run opencode attach <server-url> from the TUI |
Chooses an available port and binds to 127.0.0.1 by default |
| Desktop | Desktop application | Runs a local opencode-cli sidecar by default |
Configure Desktop to use the desired server URL | Depends on the selected local or remote server |
The exact defaults and flags can change because the documentation is maintained on OpenCode’s development branch. Check the help output and settings shipped with your installed release when a port, hostname or option matters.
serve versus web
Use opencode serve when you need a backend for an API client or another interface but do not need OpenCode to open a browser. Use opencode web when the browser interface is part of the workflow. Both are server-starting paths, but they are not interchangeable from a user-experience perspective.
The server guide lists port 4096 and hostname 127.0.0.1 as the documented defaults for serve. The web command chooses an available port by default. If you are attaching a TUI, do not assume the port: copy the URL printed by the running command or inspect the service output.
Localhost, LAN access and authentication
Binding to 127.0.0.1 limits access to the same machine. This is the appropriate default for a browser and terminal that run locally. Binding to 0.0.0.0 listens on network interfaces, allowing another machine or environment to reach the service, but it also makes the server potentially reachable by other users on that network.
The web documentation says to set OPENCODE_SERVER_PASSWORD when exposing the service for network access. Without a password, an exposed service is unsecured. The default HTTP Basic Authentication username is opencode; the documentation also provides an environment-variable mechanism to override that username for installations that need a different value.
CORS and authentication solve different problems:
- CORS controls which browser origins may make cross-origin requests. It is a browser policy mechanism.
- Password authentication verifies access to the server. It is the protection to use when the service is reachable beyond a trusted localhost-only setup.
Allowing a CORS origin does not protect an exposed service. Conversely, a password does not make an incorrectly configured browser origin work; both settings may be needed for a remote browser client.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Using OpenCode from Windows and WSL
The web documentation recommends running the web command from WSL on Windows when you need reliable file-system access and terminal integration. In that arrangement, the OpenCode server runs inside WSL and the browser or another client connects to the address exposed by that environment.
Best Value
Desktop can connect to a server running in WSL. If you bind the WSL server to 0.0.0.0, protect it with OPENCODE_SERVER_PASSWORD as recommended in the documentation. Also verify that the selected Desktop URL resolves to the WSL service from the Desktop process; localhost addresses can behave differently across Windows and WSL networking modes.
Why sessions appear to be missing
You started a second server
The most common explanation is that the client is connected to a different process. Compare the complete server URLs, including ports, and identify which command started each process. Attach the TUI to the URL printed by opencode web rather than launching an unrelated TUI server.
Desktop is still using its sidecar
Check Desktop’s selected server URL. A local sidecar is the default, so sessions created through a separately launched web service will not appear unless Desktop is configured to use that same service.
Free tools Windows power users keep installed
One-click scans. No signup required.
The server is listening only on localhost
A client on another machine cannot reach a service bound to 127.0.0.1. Choose an appropriate hostname for the server, configure the network path, and add password protection before exposing it beyond the local machine.
Authentication or browser policy blocks the request
If a remote client receives an authentication failure, verify OPENCODE_SERVER_PASSWORD and the credentials being supplied. If the browser reports a cross-origin error, review the allowed CORS origins. Do not treat a CORS change as a substitute for authentication.
The WSL and Windows paths do not match
When the server runs in WSL, confirm that the files and terminal commands you expect are available in that environment. A connection can succeed while the requested project path is wrong because the server sees WSL’s file system, not necessarily the path spelling used by a Windows client.
A reliable setup checklist
- Decide whether the server should be local-only or reachable from another machine.
- Choose one startup path: TUI,
serve,webor Desktop’s sidecar. - Write down the server URL, including its port.
- Point every client that should share sessions at that exact URL.
- For network access, bind deliberately, set
OPENCODE_SERVER_PASSWORD, and configure browser origins only when required. - After changing clients, verify the selected URL before troubleshooting sessions, files or authentication.
What to remember
OpenCode’s terminal, web and Desktop experiences are different clients around a server. The terminal can attach to the server started by opencode web, which is the documented way to share sessions and state between those two interfaces. Desktop uses a local server sidecar by default and shares the web server only when you explicitly configure the same server URL. Treat each server process as an independent backend, keep localhost-only services private, and add password authentication before making one reachable on a network.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
