Run as a GitHub Codespace

A third home for the same image, alongside Hugging Face Spaces and Railway, and
the only one that needs no account the user does not already have.

A dev container starts with its entrypoint overridden, so the image's ENTRYPOINT
never runs and the server has to be started explicitly. That happens in
postStartCommand rather than postCreateCommand because codespaces stop after 30
minutes idle: only postStartCommand runs again on resume, which is what makes this
behave like a server instead of a dev box to be restarted by hand.

The port is declared public in portsAttributes because there is no REST endpoint
for port visibility — a client that provisions codespaces cannot otherwise expose
anything without a human toggling it in the UI. Public is only safe here because
entrypoint.sh refuses to start without OPENCODE_SERVER_PASSWORD; every route on
this server runs shell commands, so a missing password has to fail loudly rather
than publish an open shell.

State goes under /workspaces rather than /data, which does not exist in a
codespace, so sessions and code survive an idle stop and are lost only when the
codespace itself is deleted.

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

.devcontainer/devcontainer.json

@@ -0,0 +1,58 @@
+// opencode-cloud as a GitHub Codespace — a third home alongside Hugging Face Spaces and
+// Railway.
+//
+// The same Dockerfile serves all three. What differs here is that a dev container starts with
+// its entrypoint overridden, so the image's ENTRYPOINT never runs: the server has to be
+// started explicitly, and started again after every idle stop.
+//
+// Codespaces stop after 30 minutes idle by default. That is fine for this use — a stopped
+// codespace keeps its disk and restarts under the same name and URL — but it does mean
+// postStartCommand, not postCreateCommand, is what boots the server, because only the former
+// runs on every resume.
+{
+  "name": "opencode-cloud",
+  "build": {
+    "dockerfile": "../Dockerfile"
+  },
+
+  // uid 1000, matching the image. The Dockerfile creates nothing else.
+  "remoteUser": "node",
+
+  // Hugging Face has no $PORT and falls back to 7860; keep the same here so one number
+  // describes the server everywhere.
+  "containerEnv": {
+    "PORT": "7860",
+    // entrypoint.sh persists sessions, logins and code under this root when it is writable.
+    // /data does not exist in a codespace, but /workspaces survives stop/start, so state
+    // outlives an idle timeout and is lost only when the codespace itself is deleted.
+    "OPENCODE_STATE_ROOT": "/workspaces/.opencode-state"
+  },
+
+  "forwardPorts": [7860],
+  "portsAttributes": {
+    "7860": {
+      "label": "opencode",
+      // The only way to expose a port without a human toggling it: there is no REST endpoint
+      // for port visibility, so a client that provisions codespaces has to declare it here.
+      //
+      // Public is safe *because* entrypoint.sh refuses to start without
+      // OPENCODE_SERVER_PASSWORD. Every route on this server runs shell commands, so basic
+      // auth is the only thing in front of it; a missing password fails loudly rather than
+      // publishing an open shell.
+      "visibility": "public",
+      "onAutoForward": "silent"
+    }
+  },
+
+  // Runs on create *and* on every resume from an idle stop, which is what makes the codespace
+  // behave like a server rather than a dev box you have to log into and restart by hand.
+  // Backgrounded so the codespace can finish starting; the log is where a refused boot
+  // (usually a missing password) explains itself.
+  "postStartCommand": "nohup /home/node/entrypoint.sh > /tmp/opencode.log 2>&1 & echo started",
+
+  "customizations": {
+    "vscode": {
+      "extensions": []
+    }
+  }
+}

README.md

@@ -74,6 +74,35 @@ with mount path `/data` for persistence. Details and caveats: [docs/RAILWAY.md](
 
 ---
 
+## Run as a GitHub Codespace
+
+```
+Code -> Codespaces -> Create codespace on main
+```
+
+Set `OPENCODE_SERVER_PASSWORD` first, as a **Codespaces** secret — repository secrets
+and Actions secrets are separate and are not visible here:
+
+```bash
+gh secret set OPENCODE_SERVER_PASSWORD --app codespaces --repo OWNER/REPO
+```
+
+`.devcontainer/devcontainer.json` builds the same Dockerfile, forwards 7860 publicly and
+starts the server on `postStartCommand`. Public is safe only because `entrypoint.sh` refuses
+to start without a password; without the secret the codespace comes up with no server and the
+reason is in `/tmp/opencode.log`.
+
+Unlike a Space or a Railway service, a codespace **stops after 30 minutes idle** (240 maximum).
+It keeps its disk and restarts under the same name and URL, and `postStartCommand` boots the
+server again — but it is not always-on, and GitHub deletes a stopped codespace after the
+retention period, up to 30 days. State lives under `/workspaces/.opencode-state`, so it
+survives a stop and is lost only with the codespace itself.
+
+A personal Free account includes 120 core-hours a month, which is roughly 60 hours of wall
+clock on a 2-core machine; the idle timeout is what keeps that from draining.
+
+---
+
 ## Keeping the Space in sync with GitHub
 
 `.github/workflows/sync-to-hf-space.yml` builds the image, boots it, checks that
@@ -150,7 +179,7 @@ removed and nothing advertises the capability.
 | `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_STATE_ROOT` | `/data` | Where to look for a writable volume. Codespaces sets `/workspaces/.opencode-state`. |
 | `OPENCODE_WORKSPACE` | `$STATE_ROOT/workspace` or `$HOME/workspace` | Directory to serve. |
 | `OPENCODE_CORS_ORIGINS` | — | Comma-separated extra CORS origins. |
 | `HF_TOKEN` | — | Optional. A Hugging Face token, which lets the agent create and manage HF repos with the bundled `hf` CLI. See the warning below. |