Add deployable opencode server image for HF Spaces and Railway

One Dockerfile serving both hosts. entrypoint.sh resolves the port at runtime
($PORT on Railway, 7860 to match app_port on HF Spaces), detects a writable
/data mount and points the XDG dirs and workspace at it so sessions, provider
logins and code survive restarts, and refuses to start without
OPENCODE_SERVER_PASSWORD — every route on this server allows shell execution,
so basic auth is not optional on a public URL.

opencode is installed at build time rather than on first boot, since a free
Space's filesystem is ephemeral and would otherwise re-download the release on
every cold start. The installer hardcodes $HOME/.opencode/bin and ignores
OPENCODE_INSTALL_DIR, so the binary is moved onto the shared PATH afterwards.
The node images already ship a uid-1000 user, which is what HF Spaces requires,
so `node` is reused instead of adding a colliding one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,5 @@
+.env
+.env.*
+!.env.example
+node_modules/
+.DS_Store

Dockerfile

@@ -0,0 +1,45 @@
+# opencode-cloud — one image, two homes (Hugging Face Spaces + Railway).
+#
+# The port is decided at runtime by entrypoint.sh:
+#   * Railway injects $PORT
+#   * HF Spaces does not, so we fall back to 7860 (matches app_port in README.md)
+FROM node:22-bookworm-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      ca-certificates \
+      curl \
+      git \
+      jq \
+      less \
+      openssh-client \
+      ripgrep \
+      tar \
+      unzip \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install opencode at BUILD time so cold starts don't re-download the release.
+# The official installer hardcodes $HOME/.opencode/bin (it ignores
+# OPENCODE_INSTALL_DIR), so move the binary onto the shared PATH afterwards.
+# Pin a release with:  --build-arg OPENCODE_VERSION=1.18.18
+ARG OPENCODE_VERSION=""
+RUN VERSION="${OPENCODE_VERSION}" bash -c 'curl -fsSL https://opencode.ai/install | bash' \
+    && mv "$HOME/.opencode/bin/opencode" /usr/local/bin/opencode \
+    && chmod 755 /usr/local/bin/opencode \
+    && rm -rf "$HOME/.opencode" \
+    && opencode --version
+
+# Hugging Face Spaces runs containers as uid 1000. The node images already ship
+# a `node` user at uid 1000, so reuse it rather than useradd'ing a colliding one.
+ENV HOME=/home/node
+ENV PATH=/usr/local/bin:${PATH}
+
+COPY --chown=node:node entrypoint.sh /home/node/entrypoint.sh
+RUN chmod +x /home/node/entrypoint.sh \
+    && mkdir -p /home/node/workspace \
+    && chown -R node:node /home/node
+
+USER node
+WORKDIR /home/node/workspace
+
+EXPOSE 7860
+ENTRYPOINT ["/home/node/entrypoint.sh"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 polats
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,119 @@
+---
+title: OpenCode Cloud
+emoji: 🤖
+colorFrom: gray
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# opencode-cloud
+
+Run [opencode](https://opencode.ai) — an open source AI coding agent — as a hosted
+server you reach from a browser, from the desktop app, or from a local build of the
+web app. One Dockerfile, deployable to **Hugging Face Spaces** or **Railway**.
+
+`opencode serve` is not just an API: the server also serves the web UI on its
+catch-all route, so opening the deployment URL gives you the full app, same-origin.
+
+---
+
+## Deploy on Hugging Face Spaces
+
+1. **Create a Space** → SDK **Docker**, blank template. Push this repo to it
+   (or duplicate an existing Space built from it).
+2. **Settings → Variables and secrets** and add:
+
+   | Secret | Required | Notes |
+   |---|---|---|
+   | `OPENCODE_SERVER_PASSWORD` | **yes** | The container refuses to start without it. This is the only thing protecting a shell. |
+   | `OPENCODE_SERVER_USERNAME` | no | Defaults to `opencode`. |
+   | `OPENCODE_API_KEY` | pick ≥1 | [opencode zen](https://opencode.ai/zen) curated models |
+   | `ANTHROPIC_API_KEY` | pick ≥1 | https://console.anthropic.com |
+   | `OPENAI_API_KEY` | pick ≥1 | https://platform.openai.com/api-keys |
+   | `GEMINI_API_KEY` | pick ≥1 | https://aistudio.google.com/apikey |
+
+3. Open the Space URL and log in with `opencode` + your password.
+
+Provider keys work as plain env vars — opencode registers any provider whose
+models.dev env var is present, no login step needed.
+
+### Persistence
+
+Free Spaces are **ephemeral** and are stopped after ~48h idle. Sessions, provider
+logins and any uncommitted code are lost on restart. Two options:
+
+- **Free:** `git clone` your repo into the workspace and push before you walk away.
+- **Paid:** enable persistent storage (Settings → Storage). It mounts at `/data`,
+  which `entrypoint.sh` detects and uses for the XDG dirs *and* the workspace, so
+  state survives restarts. Watch the boot log — it prints which mode it picked.
+
+### Public or private Space?
+
+A **private** Space adds your HF login in front of everything, which is the safer
+default for browser use. The catch: HF authenticates private Spaces with an
+`Authorization: Bearer hf_…` header, and opencode wants `Authorization: Basic …` —
+one header, two claimants. So a private Space works in a browser (HF session
+cookie) but a **desktop-app or local-app connection to a private Space will fight
+over that header**. Keep the Space public with a long password if you want those.
+
+---
+
+## Deploy on Railway
+
+```bash
+railway init                       # or point a service at this GitHub repo
+railway variables --set OPENCODE_SERVER_PASSWORD=...
+railway up
+```
+
+Railway injects `$PORT`, which `entrypoint.sh` uses automatically. Attach a volume
+with mount path `/data` for persistence. Details and caveats: [docs/RAILWAY.md](docs/RAILWAY.md).
+
+---
+
+## Connecting the desktop app or a local web app
+
+You don't have to use the in-browser UI. In the app, **Settings → Servers → Add**
+and enter the deployment URL plus the username/password. The server's CORS
+allowlist already covers `localhost`, `*.opencode.ai` and the desktop app's
+`oc://renderer` origin, so no extra flags are needed. Only a frontend you host on
+your own domain needs `OPENCODE_CORS_ORIGINS=https://your.domain`.
+
+---
+
+## Read this before you deploy
+
+- **This is a remote shell.** Every route allows command execution and file
+  read/write in the container. Basic auth over HTTPS is the entire security model,
+  so use a long random password, and think twice about what credentials you put in
+  the container alongside it.
+- **Provider OAuth "login with browser" flows don't work on a remote server.**
+  They bind a `http://localhost:<port>/auth/callback` listener *inside* the
+  container, so your browser is redirected to your own machine instead. Use API
+  keys.
+- **CPU only, and modest.** Fine for the agent; you can't run local models.
+- **Check the host's terms.** A general-purpose remote shell is not the ML-demo
+  use case Spaces are described for; a public one with a weak password is the way
+  to get flagged.
+
+---
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `OPENCODE_SERVER_PASSWORD` | — | **Required.** Basic auth password. |
+| `OPENCODE_SERVER_USERNAME` | `opencode` | Basic auth username. |
+| `PORT` | `7860` | Listen port. Railway sets this; HF must match `app_port`. |
+| `OPENCODE_STATE_ROOT` | `/data` | Where to look for a writable volume. |
+| `OPENCODE_WORKSPACE` | `$STATE_ROOT/workspace` or `$HOME/workspace` | Directory to serve. |
+| `OPENCODE_CORS_ORIGINS` | — | Comma-separated extra CORS origins. |
+
+Build arg `OPENCODE_VERSION` pins a release (default: latest).
+
+---
+
+MIT. opencode itself is © Anomaly Innovations; this repo is deployment wrapper code.

docs/RAILWAY.md

@@ -0,0 +1,46 @@
+# Deploying on Railway
+
+Railway is the sturdier of the two targets: no port/`app_port` coupling, cheap
+volumes, and no always-on/idle-GC surprises. There is no free always-on tier.
+
+## Steps
+
+1. Create a project and point a service at this repo (or `railway init` + `railway up`).
+   `railway.json` selects the Dockerfile builder.
+2. Set variables:
+
+   ```bash
+   railway variables --set OPENCODE_SERVER_PASSWORD="$(openssl rand -base64 24)"
+   railway variables --set OPENCODE_API_KEY=...        # and/or ANTHROPIC_API_KEY, etc.
+   ```
+
+3. **Attach a volume** with mount path `/data`. Without it, every redeploy wipes
+   sessions, provider logins and uncommitted code. `entrypoint.sh` picks `/data`
+   up automatically and logs which mode it chose.
+4. Generate a domain (Settings → Networking → Generate Domain) and open it.
+
+`$PORT` is injected by Railway and used automatically — do not hardcode a port.
+
+## Do not set a healthcheck path
+
+Every route requires basic auth, so `/api/health` returns `401` to an
+unauthenticated prober and Railway would mark the deploy failed. Leave
+`healthcheckPath` unset and let Railway consider the service live once the
+process is listening.
+
+## Getting your code in
+
+There is no repo in the container. From the app's terminal:
+
+```bash
+git clone https://github.com/you/your-repo.git
+```
+
+For pushes, add a deploy key or use a PAT. Anything outside `/data` is lost on
+redeploy.
+
+## Restarts kill in-flight runs
+
+A redeploy or crash takes the container with it, including any agent run in
+progress. Session state survives if it lives on the volume; the interrupted run
+does not.

entrypoint.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Boot opencode's headless server for a PaaS (Hugging Face Spaces / Railway).
+set -euo pipefail
+
+# Allow `docker run <image> bash` etc. to override the server for debugging.
+# PaaS hosts pass no arguments, so the normal path is unaffected.
+if [ "$#" -gt 0 ]; then
+  exec "$@"
+fi
+
+# --- port -------------------------------------------------------------------
+# Railway injects $PORT. HF Spaces does not; 7860 must match app_port in README.md.
+PORT="${PORT:-7860}"
+
+# --- refuse to run unauthenticated -----------------------------------------
+# opencode itself only warns. On a public URL an unauthenticated server means
+# anyone can run shell commands and read/write files in this container, so fail
+# loudly instead.
+if [ -z "${OPENCODE_SERVER_PASSWORD:-}" ]; then
+  cat >&2 <<'MSG'
+FATAL: OPENCODE_SERVER_PASSWORD is not set.
+
+  Every route on this server allows shell execution and file access, and basic
+  auth is the only thing standing in front of it. Set the secret and redeploy:
+
+    Hugging Face  Settings -> Variables and secrets -> New secret
+    Railway       Variables -> New Variable
+
+  Log in as $OPENCODE_SERVER_USERNAME (default "opencode") with that password.
+MSG
+  exit 1
+fi
+
+# --- persistence -----------------------------------------------------------
+# opencode keeps sessions, provider credentials and its SQLite DB under the XDG
+# dirs (packages/core/src/global.ts), so pointing those at a mounted volume is
+# what makes state survive a restart.
+#   HF Spaces  persistent storage is mounted at /data (paid add-on)
+#   Railway    attach a volume with mount path /data
+STATE_ROOT="${OPENCODE_STATE_ROOT:-/data}"
+
+if [ -d "$STATE_ROOT" ] && [ -w "$STATE_ROOT" ]; then
+  export XDG_DATA_HOME="$STATE_ROOT/share"
+  export XDG_STATE_HOME="$STATE_ROOT/state"
+  export XDG_CACHE_HOME="$STATE_ROOT/cache"
+  export XDG_CONFIG_HOME="$STATE_ROOT/config"
+  WORKSPACE="${OPENCODE_WORKSPACE:-$STATE_ROOT/workspace}"
+  mkdir -p "$XDG_DATA_HOME" "$XDG_STATE_HOME" "$XDG_CACHE_HOME" "$XDG_CONFIG_HOME"
+  echo "persistence: $STATE_ROOT (sessions, logins and code survive restarts)"
+else
+  WORKSPACE="${OPENCODE_WORKSPACE:-$HOME/workspace}"
+  echo "persistence: NONE — $STATE_ROOT is not a writable mount."
+  echo "             Sessions, provider logins and uncommitted code are lost on restart."
+  echo "             Push to git before you walk away, or attach a volume at $STATE_ROOT."
+fi
+
+mkdir -p "$WORKSPACE"
+cd "$WORKSPACE"
+
+# Volumes and bind mounts routinely carry a different owner than uid 1000,
+# which makes git refuse to touch the repo. Trust what we already control.
+git config --global --add safe.directory '*' 2>/dev/null || true
+
+# --- extra CORS origins ----------------------------------------------------
+# localhost, *.opencode.ai and the desktop app's oc://renderer are allowed out
+# of the box (packages/server/src/cors.ts). Only a frontend you host yourself
+# on some other domain needs this.
+CORS_ARGS=()
+if [ -n "${OPENCODE_CORS_ORIGINS:-}" ]; then
+  IFS=',' read -ra origins <<<"$OPENCODE_CORS_ORIGINS"
+  for origin in "${origins[@]}"; do
+    origin="$(echo "$origin" | xargs)"
+    [ -n "$origin" ] && CORS_ARGS+=(--cors "$origin")
+  done
+fi
+
+echo "opencode $(opencode --version) starting on 0.0.0.0:$PORT (workspace: $WORKSPACE)"
+exec opencode serve --hostname 0.0.0.0 --port "$PORT" "${CORS_ARGS[@]}"

railway.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "DOCKERFILE",
+    "dockerfilePath": "Dockerfile"
+  },
+  "deploy": {
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 10,
+    "numReplicas": 1
+  }
+}