File size: 3,645 Bytes
7ca4acf | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 | ---
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.
|