---
title: "Run OpenCode on a remote server"
description: "OpenCode on your own VM, wired to Claude, GPT and open models with no API keys. Code from your terminal or a private browser tab, laptop optional."
url: https://exe-staging.dev/deploy/opencode
category: "AI agents"
updated: 2026-10-17
---

# Run OpenCode on a remote server

Every model, one VM, and an agent that works while your laptop sleeps.

- **Software:** OpenCode (https://opencode.ai/)
- **Source:** https://github.com/anomalyco/opencode
- **License:** MIT
- **Time:** 5 minutes
- **Example VM name:** `my-opencode` (yours will differ; on the VM, `hostname` prints it)
- **Machine-readable:** https://exe-staging.dev/deploy/opencode/manifest.json

## What you get

- OpenCode connected to Claude, GPT and open models, with no API key to paste
- A project folder at `~/project` on persistent disk
- An `opencode` tmux session that survives disconnects
- OpenCode's web app on port 4096, behind exe.dev login, and back after a reboot

Running on the VM:

- **OpenCode**: connected to exe.dev's LLM integration, port 4096, data in `~/.local/share/opencode`
- **Your project**, data in `~/project`
- **tmux**: keeps your terminal session running when you disconnect

How it is reached:

- ssh my-opencode.exe.xyz (private): your terminal
- https://my-opencode.exe.xyz:4096/ (private): OpenCode in your browser, after a one-time sign-in link

## Deploy with Shelley

Open https://exe-staging.dev/new?prompt=Set%20up%20OpenCode%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe-staging.dev%2Fdeploy%2Fopencode.md%20from%20top%20to%20bottom.%0A%0AThe%20recipe%27s%20example%20VM%20name%20is%20my-opencode.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-opencode.%20Skip%20the%20step%20that%20creates%20the%20VM%3B%20you%20are%20on%20it.%0A%0AYou%20are%20done%20when%20all%20of%20these%20are%20true.%20Check%20each%20one%20yourself%3A%0A-%20OpenCode%20connected%20to%20Claude%2C%20GPT%20and%20open%20models%2C%20with%20no%20API%20key%20to%20paste%0A-%20A%20project%20folder%20at%20%60~%2Fproject%60%20on%20persistent%20disk%0A-%20An%20%60opencode%60%20tmux%20session%20that%20survives%20disconnects%0A-%20OpenCode%27s%20web%20app%20on%20port%204096%2C%20behind%20exe.dev%20login%2C%20and%20back%20after%20a%20reboot%0A%0ARun%20the%20VM-side%20setup%20in%20%22Start%20coding%22%20and%20%22Open%20it%20in%20your%20browser%22.%0AIf%20%60~%2F.config%2Fopencode%2Fopencode.json%60%20holds%20more%20than%20exe.dev%27s%0Aplaceholder%20%28%60%24schema%60%20and%20%60autoupdate%60%29%2C%20add%20the%20%60model%60%20and%20%60providers%60%0Asettings%20to%20it%20instead%20of%20replacing%20it.%20Create%20tmux%20detached%0A%28%60tmux%20new%20-d%20-s%20opencode%20-c%20~%2Fproject%60%29%20rather%20than%20attaching.%20Reuse%20the%0Asession%20if%20it%20already%20exists.%20Do%20not%20launch%20interactive%20OpenCode.%20Do%20not%0Acreate%20a%20pairing%20link%3B%20they%20expire%20in%20five%20minutes.%20Verify%20from%20~%2Fproject%0Awith%20%60opencode%20run%20-m%20anthropic%2Fclaude-haiku-5-5%20%22Reply%20with%20exactly%3A%20OK%22%60%2C%0Acheck%20%60tmux%20has-session%20-t%20opencode%60%2C%20and%20check%20that%20%60opencode%20service%0Astatus%60%20prints%20%60http%3A%2F%2F0.0.0.0%3A4096%60%20and%20%60systemctl%20is-enabled%20opencode%60%0Aprints%20%60enabled%60.%20Skip%20the%20later%20optional%20instructions%20and%20FAQ.%20Finish%0Awith%20the%20SSH%20command%20from%20%22Take%20a%20break%22%2C%20the%20browser%20URL%2C%20and%20the%0A%60opencode%20pair%60%20command%20from%20%22Open%20it%20in%20your%20browser%22%2C%20using%20this%20VM%27s%0Aname%2C%20and%20tell%20the%20owner%20to%20run%20%60opencode%60%20inside%20the%20tmux%20session.%0A%0AFinish%20with%20the%20URLs%20I%20should%20open.%0A to create a VM whose agent, Shelley, follows this recipe. From a terminal:

```sh
curl -fsSL https://exe-staging.dev/deploy/opencode/prompt.txt | ssh exe.dev new --prompt=/dev/stdin
```

Or follow the steps below by hand.

OpenCode is an open-source coding agent that works with almost any model.
On an exe.dev VM it gets Claude, GPT and open-weight models through exe.dev's
[LLM integration](/docs/integrations-llm): no API keys to paste, and model
usage billed to your exe.dev account.

Use it from your terminal, or from a browser tab that only you can open.
Either way, the work happens on the VM, so your laptop can go to sleep.

## Start coding

On your computer, create a VM and connect. Pick any free name; if you've
already clicked Deploy or have a VM, skip the first command and use its name:

```bash
ssh exe.dev new --name=my-opencode
ssh my-opencode.exe.xyz
```

On the VM, update OpenCode to its latest release and point its Anthropic,
OpenAI and Fireworks providers at exe.dev's LLM gateway. This replaces
settings left over from OpenCode 1:

```bash
sudo exeuntu update opencode
rm -f ~/.config/opencode/plugins/exe-dev.js
cat > ~/.config/opencode/opencode.json <<'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "providers": {
    "anthropic": { "settings": { "baseURL": "https://llm.int.exe.xyz/anthropic/v1" } },
    "openai": { "settings": { "baseURL": "https://llm.int.exe.xyz/openai/v1" } },
    "fireworks-ai": { "settings": { "baseURL": "https://llm.int.exe.xyz/fireworks/inference/v1" } }
  }
}
EOF
```

Make a project folder and open a tmux session:

```bash
mkdir -p ~/project
tmux new -A -s opencode -c ~/project
```

Inside that session, start OpenCode:

```bash
opencode
```

Give it a small task. For example:

> Build a tiny website for a bakery that only sells one kind of bread.

That's the setup. Your files live in `~/project`.

## Take a break

Press **Ctrl-b**, then **d** to detach. OpenCode keeps working on the VM when
you disconnect. On your computer, use this command to hop back in:

```bash
ssh -t my-opencode.exe.xyz 'tmux new -A -s opencode -c ~/project'
```

A VM restart ends the running session, but not your saved work. Reconnect
and run `opencode --continue` from your project's folder on the VM to pick
up its last conversation.

## Open it in your browser

OpenCode runs a background service on the VM that holds your sessions, and
that service also serves a web app. On the VM, give the service a fixed port
that exe.dev's proxy can reach, and start it whenever the VM boots:

```bash
opencode service set port 4096
opencode service set hostname 0.0.0.0
sudo tee /etc/systemd/system/opencode.service >/dev/null <<'EOF'
[Unit]
Description=Start the OpenCode background service
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
User=exedev
ExecStart=/usr/local/bin/opencode service start

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now opencode
```

Then open `https://my-opencode.exe.xyz:4096/` in your browser. exe.dev asks
you to log in, because port 4096 is private to people with access to the
VM, and then OpenCode asks for a pairing link. Get one from your computer:

```bash
ssh my-opencode.exe.xyz opencode pair --url https://my-opencode.exe.xyz:4096
```

Open the link it prints within five minutes. OpenCode remembers that
browser for 30 days and shows the same sessions as your terminal. Each link
works once, so run the command again for another browser, or scan the QR
code it prints with your phone.

> [!WARNING]
> The web app can run any command on the VM. Leave port 4096 private and
> share sign-in links only with people you'd hand your SSH key to.

## Make yourself at home

- **Pick a model:** type `/models` in OpenCode, or run `opencode models` to
  list them, and change `model` in `~/.config/opencode/opencode.json` to set
  the default. exe.dev keeps a [list of available models and
  prices](/llm-gateway-models). Models under `opencode/` are OpenCode's own
  free ones and don't go through exe.dev.
- **Bring your code:** [connect a GitHub repo](/docs/integrations-github),
  clone it onto the VM, and run `opencode` from its directory. Use that
  folder instead of `~/project` in the commands above.
- **Peek at your app:** ask OpenCode to serve it on `0.0.0.0:8000`, then
  open `https://my-opencode.exe.xyz/`. It's private by default.
  [More about previews](/docs/proxy).
- **Script it:** `opencode run "Summarize the TODOs in this repo"` runs one
  task without the interactive screen and prints the answer.

For OpenCode's own features, head to [the OpenCode docs](https://opencode.ai/v2/docs/).

## Frequently asked questions

### Can I use my own subscription or API key?

Yes. Type `/connect` in OpenCode to sign in with ChatGPT, GitHub Copilot or a provider's API key; see OpenCode's [provider docs](https://opencode.ai/v2/docs/providers/). Remove that provider from the `providers` section of `opencode.json` first, so OpenCode talks to it directly instead of through exe.dev.

### How do I update OpenCode?

On the VM, run `sudo exeuntu update opencode`, then `opencode service restart` so the background service picks up the new version. Your sessions and settings stay put.

### Something's not working. Where do I look?

On the VM, `opencode service status` shows the background service's address, and its log is at `~/.local/share/opencode/log/opencode.log`. If OpenCode says `1 plugin failed`, you skipped the `rm` in "Start coding": that plugin is for OpenCode 1. OpenCode's [troubleshooting guide](https://opencode.ai/v2/docs/troubleshooting/) covers the rest.

### How do I back up my work?

Commit and push your code. For a copy of the whole VM, run `ssh exe.dev cp my-opencode my-opencode-backup` on your computer (choose a free backup name). To use that copy, connect with `ssh my-opencode-backup.exe.xyz`; your files and OpenCode sessions are there. For the browser, pair again with the copy's name in `--url`. Reattach any [VM-specific integrations](/docs/integrations-attach).


## Related

- [Run Codex on a remote server](https://exe-staging.dev/deploy/codex.md): A computer for Codex. An early night for your laptop.
- [Run Claude Code on a remote server](https://exe-staging.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop.
- [VS Code in your browser, with code-server](https://exe-staging.dev/deploy/code-server.md): Your editor in a tab. Your projects right where you left them.
- [Host OpenClaw](https://exe-staging.dev/deploy/openclaw.md): An AI sidekick with its own computer. Your laptop can take a nap.
- [Self-host Hermes Agent](https://exe-staging.dev/deploy/hermes-agent.md): An agent that remembers you, on a computer that never sleeps.
- [Host a Pi Durable agent](https://exe-staging.dev/deploy/pi-durable.md): An agent that picks up where it left off, even after kill -9.