[docs] Container/server deployment: TUI entrypoint, rotating password, and a 404 health check #55558

1. The Docker image's entrypoint is the TUI, so server deploys must override the command

The docs list Docker images under Intro → Docker (ghcr.io/anomalyco/opencode:2.0.0)
and separately document opencode serve for "a shared, always-on, or remote host",
but never say the two need joining.

Observed from the image config blob:

Entrypoint : ["opencode"]
Cmd        : []
WorkingDir : /
User       : (root)

So a stock docker run ghcr.io/anomalyco/opencode:2.0.0 starts the full-screen
TUI. It must be launched as, for example:

docker run ghcr.io/anomalyco/opencode:2.0.0 \
  serve --hostname 0.0.0.0 --port 4096

Suggested fix: add a short "run it in a container / on a remote host" example
to the Web page or Docker section, including the --hostname 0.0.0.0 requirement
(the default binds localhost only, so a container port mapping gets nothing).

2. serve generates a fresh random password on every start and ignores opencode service set password

The Web docs say the server is "password protected" and give
opencode service set password "a-long-secret" under Configure. The natural
reading is that the password can be pinned for a remote host. It cannot — not
for serve.

Reproduced with a mounted config directory:

docker run --rm -v /tmp/oc-cfg:/root/.config/opencode \
  --entrypoint opencode ghcr.io/anomalyco/opencode:2.0.0 \
  service set password "pinned-secret-123"

cat /tmp/oc-cfg/service.json
# { "password": "pinned-secret-123" }        <-- written correctly

docker run --rm -d -v /tmp/oc-cfg:/root/.config/opencode -p 4096:4096 \
  ghcr.io/anomalyco/opencode:2.0.0 serve --hostname 0.0.0.0 --port 4096

docker logs <id>
# server listening on http://0.0.0.0:4096
# server password <random>        <-- NOT the pinned value

The background service does honour it:

docker exec <id> opencode service start
# request with opencode:pinned-secret-123  -> 200
# request with opencode:wrong              -> 401

Consequence for anyone deploying serve behind a supervisor: every restart
rotates the password and signs out every browser session, with no supported way
to pin it.

Suggested fix (either): have serve read the password from the service
config, or document a supported way to supply it for the foreground server
(an OPENCODE_SERVER_PASSWORD-style environment variable would fit container
deployments). At minimum, the docs should state that service set password does
not apply to serve.

3. The documented verification command returns 404 on the shipped image

The Network docs suggest:

opencode api get /api/info

Against a 2.0.0 server, with valid Basic credentials:

/api/info     -> 404
/api/location -> 200 application/json
/api/session  -> 200
/api/config   -> 200
/api/agent    -> 200
/api/provider -> 200
/api/model    -> 200
/api/mcp      -> 200
/openapi.json -> 200

/api/info appears in the published HTTP API reference (the current docs target
a newer build than the 2.0.0 image), so this is a version-skew trap: the
health check named in the docs is absent from the image the docs ship.

Suggested fix: document a health endpoint that exists across shipped images
(/api/location), or note the minimum version for /api/info.

4. Persistence is not mentioned for container or remote hosts

Nothing in the Web docs says where session state lives. From inside the image:

$ opencode debug paths
home       /root
data       /root/.local/share/opencode
cache      /root/.cache/opencode
config     /root/.config/opencode
state      /root/.local/state/opencode
bin        /root/.cache/opencode/bin
log        /root/.local/share/opencode/log
repos      /root/.local/share/opencode/repos
db         /root/.local/share/opencode/opencode.db

Without a volume at the data directory, every container redeploy starts from an
empty database and all sessions are gone.

Suggested fix: a sentence on the Web/Docker pages naming the data directory
and recommending a volume (with OPENCODE_DB as the override).

Environment

• ghcr.io/anomalyco/opencode:2.0.0 (opencode v2.0.0), linux/amd64
• Docker 29.8.2
• Client used for probing: curl with HTTP Basic auth (opencode:<password>)