OpenCode on Hugging Face Spaces

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.

How it works

• The Dockerfile installs OpenCode 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

• 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

Persistence: read this

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

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

License