Spaces:
Sleeping
Sleeping
| 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). | |
| --- | |
| ## 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 | |
| it refuses to start unauthenticated and that it serves an authenticated API and | |
| the web UI — and only then force-pushes `main` to the Space and waits for it to | |
| report `RUNNING`. A broken Dockerfile fails on the runner instead of leaving the | |
| Space stuck in `BUILD_ERROR`. | |
| Configure it under **Settings → Secrets and variables → Actions**: | |
| | Name | Kind | Notes | | |
| |---|---|---| | |
| | `HF_TOKEN` | **secret** | A Hugging Face **write** token. The HF username is derived from it, so it is the only secret needed. | | |
| | `HF_SPACE` | variable | `owner/space-name`. Optional — defaults to this GitHub repo's `owner/name`. A public Space id isn't sensitive, so a variable keeps it readable in logs; a secret of the same name also works. | | |
| GitHub is the source of truth: the sync **force-pushes**, so a commit made only | |
| in the Space's web UI will be discarded. Edit here, not there. | |
| --- | |
| ## 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`. | |
| --- | |
| ## Giving the agent Hugging Face access | |
| Set `HF_TOKEN` as a Space secret (or Railway variable) and the agent can create | |
| and manage Hugging Face repos: the official `hf` CLI is installed in the image, | |
| it picks the token up from the environment with no login step, and `entrypoint.sh` | |
| installs [`agents/hf-spaces.md`](agents/hf-spaces.md) as opencode's global | |
| `AGENTS.md` so the agent knows the recipes. With no `HF_TOKEN` set, that file is | |
| removed and nothing advertises the capability. | |
| > **This hands your HF account to whoever can reach the server.** A standard HF | |
| > write token covers every repo the account can write to — including org repos — | |
| > so the blast radius is much larger than "a shell in a container". Two things | |
| > make it meaningfully safer: | |
| > | |
| > - Use a **fine-grained token** scoped to just the permissions you need (write | |
| > access to Spaces, say) rather than an account-wide write token. | |
| > - Remember the agent reads untrusted content — repos, web pages, issue text. | |
| > Anything it reads can try to talk it into using the token. The instructions | |
| > tell it never to print the token, but that is a speed bump, not a boundary. | |
| --- | |
| ## 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. 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. | | |
| Build arg `OPENCODE_VERSION` pins a release (default: latest). | |
| --- | |
| MIT. opencode itself is © Anomaly Innovations; this repo is deployment wrapper code. | |