Run an AI coding agent with OpenCode on a VPS

Why run a coding agent on a server

A VPS gives a coding agent an always-on workspace: your repository, build tools and test services are there, and the agent keeps working while your laptop sleeps. OpenCode is an open-source terminal coding agent that works with many model providers. The model runs at the provider, so even a small server is enough. Builds and tests are what need memory.

An agent can edit files and run commands, so the safety setup matters more than the install. Use a separate low-privilege user, a project folder, permission rules and credentials that cannot do much damage.

Create a workspace user

Make a dedicated account with no sudo rights, and keep your projects in its home folder. Do not use your administrator account, and do not put production credentials on this machine. If you need a clean environment each time, use a separate small VPS that you can rebuild.

sudo adduser --gecos "" coder
sudo apt install git tmux
sudo -iu coder

sudo useradd -m coder && sudo passwd coder
sudo dnf install git tmux
sudo -iu coder

Install OpenCode

The project provides an install script, and also an npm package if you already use Node. Download the script and read it before running it.

curl -fsSL https://opencode.ai/install -o opencode-install.sh
less opencode-install.sh
bash opencode-install.sh
source ~/.bashrc
opencode --version

npm install -g opencode-ai

Connect a model provider

Start OpenCode inside a project folder and connect a provider with the /connect command, or use the auth command from the shell. Use an API key created for this purpose, with a spending limit, so you can revoke it independently. Credentials are stored for your user, so keep that account private.

mkdir -p ~/projects/demo && cd ~/projects/demo
git init
opencode auth login
opencode models

opencode

Set permission rules

OpenCode asks, allows or denies each kind of action: reading files, editing, running shell commands, fetching web pages and reaching outside the project folder. Put the rules in an opencode.json file in the project. The example asks before most things, lets common safe Git and test commands run, and blocks destructive deletes. Start strict and relax rules only when they get in your way.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "npm test*": "allow",
      "rm *": "deny",
      "sudo *": "deny"
    },
    "external_directory": "deny"
  }
}

Work from tmux so it survives disconnects

Run the agent inside tmux, a terminal multiplexer, so that it keeps running when your SSH connection drops, and you can reattach later. The tmux guide covers it in more detail.

ssh coder@YOUR_SERVER -t "tmux new -A -s agent"

cd ~/projects/demo && opencode

Use it without the interface

For scripts and scheduled jobs, run a single prompt without the interface. For other tools to talk to it, there is a headless server mode. Protect the server with a password, keep it on localhost and reach it through an SSH tunnel. Never expose it to the internet, because it can run commands for whoever connects.

opencode run "Summarise the structure of this repository"

export OPENCODE_SERVER_PASSWORD="$(openssl rand -hex 24)"
opencode serve --hostname 127.0.0.1 --port 4096

ssh -N -L 4096:127.0.0.1:4096 coder@YOUR_SERVER

Give it access to your repository safely

Use a read-only deploy key for pulling and, if the agent must push, a separate key limited to a branch or a fork, as in the Git deployment guide. Do not store personal access tokens with broad rights on this server. Ask the agent to work on a branch, review the diff yourself, and merge only what you have read.

mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -f ~/.ssh/agent_key -N "" -C "agent key"
cat ~/.ssh/agent_key.pub
git checkout -b agent/first-change

Keep an eye on cost and changes

Coding agents can use many tokens on large repositories. Watch your provider's usage page, set a monthly limit and keep prompts focused. Update OpenCode with its upgrade command, and read the release notes occasionally.

opencode upgrade
git log --oneline -n 10
git diff --stat