OpenCode fails when two hosts share an NFS home directory

Description

OpenCode 1.18.19 cannot be used concurrently from two separate Linux hosts when both hosts use the same NFS-mounted home directory.

OpenCode works normally when used:

• On one host only; or
• From the same host, including with different OpenCode modes.

However, whenever OpenCode is running from one host, starting OpenCode from a second host using the same shared home directory fails, regardless of the selected mode or port.

Observed behavior:

• Starting opencode web on one host and then starting opencode on another host causes the second OpenCode instance to hang with a black screen.
• Starting opencode web from the second host fails with either ServeError, Unexpected error, or Locking protocol.
• The black screen remains indefinitely.
• Disconnecting the SSH session and starting a new session makes OpenCode usable again (assuming there is no OpenCode running on another host).
• The issue also occurs with a fresh and empty project directory, so it does not appear to depend on project-specific state.
• Using different ports does not resolve the issue.
• Using different combinations of TUI and web mode does not resolve the issue.

The hosts share an NFS-mounted home directory. The issue appears to be caused by host-independent locking or state files stored below the shared home directory.

Plugins

No response

OpenCode version

1.18.19

Steps to reproduce

Environment

• Two separate Linux hosts
• Ubuntu 24.04.4 LTS on both hosts
• NFS-mounted shared home directory
• Fish and/or Bash shells
• OpenCode 1.18.19

Reproduction

1. Log in to host A using the shared NFS home directory.

2. Start OpenCode, for example:

   npx -y opencode-ai@latest web \
     --port 8080 \
     --hostname <HOSTNAME>
   

3. Leave OpenCode running.

4. Log in to host B using the same shared NFS home directory.

5. Start OpenCode:

   opencode
   

6. Observe that the second instance hangs indefinitely with a black screen.

Alternatively:

1. Start opencode web (or just opencode) on host A.

2. Start opencode web on host B, using either the same or a different port.

3. Observe an error similar to:

   ! OPENCODE_SERVER_PASSWORD is not set; server is unsecured.
   Error: Unexpected error
   ServeError
   

   In some cases:

   Locking protocol
   

The same problem occurs when using different combinations of TUI and web mode. Changing the port does not resolve the issue.

Expected behavior

OpenCode should either:

• Support concurrent use from separate hosts sharing an NFS home directory; or
• Clearly document that a shared home directory is unsupported; or
• Use host-specific runtime and lock files so that separate hosts do not interfere with each other; or
• Fail with a clear error identifying the conflicting lock/state file and how to recover.

Actual behavior

• The second OpenCode instance hangs indefinitely with a black screen.
• opencode web may fail with ServeError, Unexpected error, or Locking protocol.
• The failure occurs even with different ports and different OpenCode modes.
• The problem occurs with a fresh and empty project.
• Disconnecting the hanging SSH session allows OpenCode to work again in a subsequent SSH session.

Screenshot and/or share link

Operating System

Ubuntu 24.04.4 LTS

Terminal

fish, bash