| --- |
| title: OpenCode Cloud |
| emoji: 🤖 |
| colorFrom: blue |
| colorTo: indigo |
| sdk: docker |
| app_port: 4096 |
| pinned: false |
| license: mit |
| --- |
| |
| # OpenCode on Hugging Face Spaces |
|
|
| Run [OpenCode](https://opencode.ai) — an open-source AI coding agent that supports 75+ LLM providers — in your browser, hosted on Hugging Face's free CPU tier. |
|
|
| ## Setup (one-time, ~2 minutes) |
|
|
| 1. **Duplicate this Space** to your own HF account (top-right → `Duplicate Space`). |
| 2. **Add your secrets** in **Settings → Variables and secrets**: |
|
|
| | Secret name | Required? | Where to get it | |
| |---|---|---| |
| | `OPENCODE_SERVER_PASSWORD` | Yes | Any password you choose — protects the web UI | |
| | `ANTHROPIC_API_KEY` | One of these | https://console.anthropic.com | |
| | `OPENAI_API_KEY` | (pick your | https://platform.openai.com/api-keys | |
| | `GEMINI_API_KEY` | provider) | https://aistudio.google.com/apikey | |
| | `OPENCODE_API_KEY` | | https://opencode.ai/zen (curated models) | |
|
|
| 3. The Space will rebuild (~60-90 seconds) and start on the URL shown above. |
| 4. Log in with username **`opencode`** and the password you set. |
|
|
| That's it. You now have a free, browser-accessible AI coding agent. |
|
|
| ## How it works |
|
|
| - The `Dockerfile` installs [OpenCode](https://opencode.ai) via the official install script and runs `opencode web`. |
| - The web UI is bound to `0.0.0.0:4096` so HF's reverse proxy can reach it. |
| - HTTP basic auth is enabled via the `OPENCODE_SERVER_PASSWORD` secret. |
| - Your workspace lives at `/home/user/workspace` inside the container. |
|
|
| ## Using OpenCode |
|
|
| Once you're in the web UI: |
|
|
| - **New session** → describe what you want to build, refactor, or fix |
| - **Files panel** → browse your workspace, upload code, or open the in-browser editor |
| - **Plan mode** (press `Tab`) → have the agent draft a plan before changing anything |
| - **Share** → get a public link to any session for sharing or debugging |
| - **`/init`** → generates an `AGENTS.md` for your project so OpenCode remembers context across sessions |
|
|
| For full usage docs, see https://opencode.ai/docs/ |
|
|
| ## Persistence: read this |
|
|
| **Free CPU Spaces are ephemeral.** Anything not pushed to git will be lost when the Space restarts (which happens after ~48h of inactivity, or when the free tier quota resets). |
|
|
| **Recommended workflow:** |
|
|
| 1. In the OpenCode terminal, `cd workspace` |
| 2. `git clone https://github.com/your-user/your-repo.git` |
| 3. Work on the project |
| 4. `git add . && git commit -m "..." && git push` before stepping away |
|
|
| For pure scratch work (no git), everything resets on restart — so commit early and often. |
|
|
| ## Caveats |
|
|
| - **CPU only** — no GPU. The agent works fine; you just can't run local LLMs here. |
| - **Sleeps after ~48h idle** on the free tier (Hugging Face does this automatically). |
| - **Resource limits** — free CPU Spaces are throttled compared to local dev. Heavy multi-file refactors can be slower. |
| - **No outbound ports** — the agent can `git clone` public repos, but you can't expose additional services. |
| - **CORS / session storage** — sessions live in the container's filesystem, so restarts wipe them. Use the `/share` command to save a session URL externally. |
|
|
| ## If you want to upgrade later |
|
|
| When you outgrow the free tier: |
|
|
| | Need | Upgrade to | |
| |---|---| |
| | Always-on, no sleep | HF Spaces paid CPU ($0.03/hr ≈ $5/mo) | |
| | Persistent storage | HF Spaces Storage bucket add-on | |
| | More CPU/RAM | Spaces hardware upgrade to `cpu-upgrade` or `cpu-performance` | |
| | Always-on + git auto-sync | Self-host on Oracle Cloud Always Free (24GB RAM, 4 ARM cores) — different guide | |
|
|
| ## License |
|
|
| MIT. OpenCode is © Anomaly. This Dockerfile is just glue. |
|
|
