OpenCode's background service: opencode service and port 49374
OpenCode 2's background service on Linux: opencode service commands, port 49374 and its password, reboots, and "Server process exited with code 1".
OpenCode 2 runs its sessions, tools and keys in one background server per Linux account, which it calls the service. The first opencode command starts it as opencode serve --service, detached, on http://127.0.0.1:49374 behind a generated password, and it keeps running after you log out. opencode service manages it: status, start, stop, restart, and get, set and unset for its settings (port, hostname, password, env, cors, remote, disabled). Nothing starts it at boot (seen on 2.1.2; 2.3.0’s docs give no boot unit either). When it fails, the reason is printed on the lines under “Error: Server process exited with code 1”; often the port is taken, and opencode service set port 4096 moves it.
What the service is
The version 2 docs put it in one sentence: “By default, OpenCode discovers or starts one shared background server for your user account.” The terminal interface, opencode run, the web interface and the desktop app are all clients of it. Version 1 has none of this; on version 1 the commands are opencode serve and opencode web, and installing OpenCode on Linux covers which version you have.
Any command that needs the server starts it if it is not running. The bare opencode command says so on standard error with Starting background server..., and after that the process belongs to no terminal: started from an SSH session, it is still there once the session has closed, with PID 1 as its parent. Two files hold it, both readable only by you:
~/.config/opencode/service.json # its settings, the password among them
~/.local/state/opencode/service.json # the running one: url, pid, version, password
~/.local/share/opencode/log/opencode.log # its logCopiedThe troubleshooting page adds a warning worth taking: “Do not delete or edit service files or the database while troubleshooting.” Change settings with the commands below instead.
The commands, as of 2.3.0
opencode service status # its address, or "stopped"
opencode service start
opencode service stop
opencode service restart
opencode service get # every setting as JSON, the password left out
opencode service get port
opencode service set port 4096
opencode service unset port # back to the default
opencode service set env OPENCODE_LOG_LEVEL DEBUG
opencode service get env # the variables you have given itCopiedThe settings set accepts are port (1 to 65535), hostname, password, cors (a comma-separated list of origins), env (one variable per command), remote and disabled (each true or false). Any other key stops with Unknown service config key. The web interface page states the catch: “Changing a setting stops the background server.” The next opencode command starts it again with the new value, or opencode service start does it at once.
A restart, or a settings change, cancels whatever the agent was running at that moment: the command in flight ends as cancelled, and the session continues when the service is back, with a note to the model that the server restarted. On a server where a long job is under way, wait for it before changing anything.
The password, and the 401
On first start the service generates a random password and saves it in its settings. opencode service get password prints it; opencode service set password <value> replaces it, which, in the docs’ words, “signs every session out” of the web interface. Anything that reaches the port without it gets 401:
curl -i http://127.0.0.1:49374/api/health # 401
curl -u "opencode:$(opencode service get password)" \
http://127.0.0.1:49374/api/health # 200CopiedThe user name is opencode. Your own OpenCode commands read the password from the service’s files and never ask for it. A client in another account, or on another machine, is pointed at the address with --server and given the password in OPENCODE_PASSWORD; without it, it stops with “Server at <url> requires a password; set OPENCODE_PASSWORD”. A browser does not use the password at all: opencode pair prints a one-time link instead, which OpenCode on a remote server covers along with reaching the web interface from a phone.
After a reboot
On OpenCode 2.1.2, as of October 2026, the installer wrote no systemd unit and nothing else that runs at boot, so after a reboot no service was running; 2.3.0’s docs describe no boot unit either. Nothing is lost: sessions, settings and the password are on disk, and the next opencode command, or opencode service start, brings the service back on the same port. What a reboot does break is anything that expects the server to be answering without you: a browser tab or phone pointed at it sees nothing until someone logs in and runs a command.
OpenCode’s docs give no unit for the background service. For a server that must come up on its own, they point at a different process: opencode serve, which “runs the same server in the foreground instead of through the shared background service,” for when you want to “run under a supervisor like systemd, Docker, or another environment that expects a foreground process.” Started that way it prints server listening on <url> and a password of its own unless OPENCODE_PASSWORD is set, it reads its environment from its own process rather than from service set env, and clients reach it with opencode --server <url>. It is a dedicated server beside the background service, not a way of starting that service.
“Error: Server process exited with code 1”
This is what the first command prints when the service could not start:
Starting background server...
Error: Server process exited with code 1
Error: Managed service port 49374 on 127.0.0.1 is already in use by another process.
Configure another port with `opencode service set port <port>` and start the service again.CopiedThe first error is only the client saying its server died. OpenCode keeps the last part of the server’s error output and prints it on the lines beneath, so the reason is there, usually one line down. When there is nothing beneath it, or the message is the shorter “Background service failed to start”, read the end of ~/.local/share/opencode/log/opencode.log, or run OpenCode with a private server so the server’s own logs come to your terminal (the --print-logs flag shows server logs only with --standalone):
tail -n 50 ~/.local/share/opencode/log/opencode.log
opencode --standalone --print-logsCopiedWhen the port is in use: four causes
The port message replaces “another process” with what holds the port when OpenCode can tell, such as already in use by PID 7763. Otherwise, see for yourself:
ss -tlnp 'sport = :49374' # something listening on it
sudo ss -tanp | grep ':49374' # any connection using it, any accountCopied- An older service that has not exited. OpenCode looks for its service through the registration file, and a service that has lost its registration but still holds the port makes the new one fail (#54267, open). The same shows as
opencode service restartfailing with “already in use by PID” while the old process carries on with its old environment (#59610). Runopencode service stop; ifssstill shows anopencodeprocess on the port, end that PID, then start again. - A second install in the same account. Another OpenCode 2 under a different home or a different
XDG_STATE_HOMEhas its own registration and the same default port (#56708). Give one of them another port. - Another Linux account. The registration is per account but the port is the machine’s, so two people on one server collide on 49374 (#50672). OpenCode’s triage there calls the fixed port “currently a deliberate default, with
opencode service set port <port>as the override.” Each account after the first sets its own. - An outgoing connection, with nothing listening. Linux hands out local ports for outgoing connections from 32768 to 60999 by default, and 49374 is inside that range, so any program’s connection can be holding it at the moment the service starts (#62891, open and reproduced on 2.2.6).
ss -tlnpshows nothing, the second command shows an established connection. Moving to another port inside the range only moves the odds; pick one below 32768.
For all four the fix is the one the message gives, with a port outside that range:
opencode service set port 4096
opencode service start
opencode service status # http://127.0.0.1:4096CopiedA port in use is not the only reason the server exits. If you ever ran sudo opencode, files in your home may now belong to root, and the service then exits on EPERM: operation not permitted, chmod '…/opencode.db' (#57032) or EACCES: permission denied, mkdir '~/.local/state/opencode' (#63789). Stop OpenCode and give the folders back to your account with sudo chown -R "$USER": ~/.local/share/opencode ~/.local/state/opencode.
The service has its own environment
Because the service outlives the shell that started it, a variable you export later does not reach it. The network page: “Shell exports affect a background service only when that service starts from the shell.” A provider key, a proxy or a company certificate goes into the service’s settings instead:
opencode service set env ANTHROPIC_API_KEY sk-ant-...
opencode service set env HTTPS_PROXY http://proxy.example.com:8080
opencode service set env NO_PROXY localhost,127.0.0.1,::1
opencode service set env NODE_EXTRA_CA_CERTS /etc/company/ca.pem
opencode service startCopiedKeep NO_PROXY in your shell too when the shell sets a proxy, because, as the page puts it, “managed service variables apply to the server process, not the CLI process,” and the client reaches the service on localhost. opencode service get env prints the values in full, keys included, so do not paste its output anywhere. The same holds for MCP servers that read a variable: they run inside the service and see its environment, not your shell’s.
opencode service set hostname 0.0.0.0
opencode pair suggests this line for connecting other devices, and the docs gloss it as “Listen on every network interface.” On a rented server, every interface includes the public address. The service then answers anyone on the internet who finds the port, over plain HTTP, with only its password and the pairing links between them and an agent that can run commands in your account. Unless a firewall in front of the machine drops that traffic, do not use it.
Bind it to a private address instead. With Tailscale on the server, tailscale ip -4 prints an address only your own devices reach:
opencode service set hostname $(tailscale ip -4)
opencode service startCopiedThe other route needs no setting at all: leave it on 127.0.0.1 and forward the port over SSH, ssh -L 49374:127.0.0.1:49374 your-server. Tailscale on an agent’s server covers the private network, and opencode service unset hostname puts the service back on localhost.
--standalone, and doing without the service
--standalone runs one command with a private server of its own instead of the shared one, which lives and dies with that command and reads that command’s environment. It is the way round a service that will not start while you find out why, and the docs use it for CI: “pass a provider API key as a secret and use standalone mode so the private server receives it.”
ANTHROPIC_API_KEY=sk-ant-... opencode run --standalone "summarise the README"CopiedTo make that the default for every command, opencode service set disabled true stops the service and leaves it off; opencode service start can still start it by hand, and opencode service unset disabled returns to the shared service. While it is disabled, pairing is unavailable, since it needs the shared service.