How to Install OpenCode on Ubuntu 24.04 with API or Ollama Models

TL;DR:

• Install OpenCode 2 as a separate Linux user with curl -fsSL https://opencode.ai/v2/install | bash, connect a model with opencode auth login, and run it in tmux so sessions survive SSH disconnects.
• The older https://opencode.ai/install script installs OpenCode 1.x. The /v2/install script installs OpenCode 2.
• API models from OpenRouter, Anthropic or OpenAI run inference off the server. A local Ollama model needs a context of at least 64,000 tokens, and Ollama defaults to 4,096 without a GPU.
• OpenCode 2 runs shell commands without asking by default. 9 permission rules make it ask first and block sudo and git push.
• The OpenCode server listens on 127.0.0.1 port 49374, so UFW only opens OpenSSH (22/tcp).
• On a High Performance hvm.xlarge plan (16 vCPU, no GPU), Qwen3.6 35B-A3B generated 14.24 tokens/s with an 8K prompt.

Applies to: Ubuntu 24.04 LTS · OpenCode 2.0.22 · Ollama 0.35.1 · checked October 2026

OpenCode is an open source AI coding agent, released under the MIT License by Anomaly at github.com/anomalyco/opencode (formerly sst/opencode), that reads a project, edits files and runs shell commands from a terminal interface. It is a separate project from the archived opencode-ai/opencode, which continues as Crush. This tutorial installs OpenCode 2 on an Ubuntu 24.04 Linux VPS under an unprivileged user, connects an API provider or a local Ollama model, and keeps sessions running in tmux after you disconnect.

Prerequisites

• A server running Ubuntu 24.04 LTS with 2 GB RAM or more for API models, or 16 to 32 GB RAM for a local model. On Arct Cloud, Linux images accept an SSH public key at deploy and give root SSH access, a General Purpose vm.nano plan (1 vCPU, 2 GB RAM, 25 GB NVMe) meets the API minimum, and the local-model figures in Step 7 come from a High Performance hvm.xlarge plan (16 vCPU, 32 GB RAM). See Linux VPS plans.
• A non-root user with sudo privileges and SSH key login. With only root access, create that user first: How to Generate an SSH Key covers giving a sudo user the same key.
• An API key from OpenRouter, Anthropic or OpenAI, unless you use only Ollama.
• A Git repository for the agent to work on.

Ubuntu 26.04 LTS uses the same OpenCode and Ollama installers, which are distribution-neutral shell scripts. This tutorial was checked on 24.04. Replace values written in capitals, such as YOUR_SERVER_IP, with your own.

Step 1: Update the server and enable the firewall

Update the packages and install Git, tmux, curl and zstd as the sudo user. The Ollama installer in Step 7 needs zstd to unpack its package:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git tmux curl zstd

Allow SSH before you enable the Uncomplicated Firewall (UFW), or the current session drops:

sudo ufw allow OpenSSH
sudo ufw enable

Type y to confirm. OpenCode and Ollama listen only on the loopback address, so no other port opens.

Step 2: Create an unprivileged user for OpenCode

OpenCode's shell tool runs with the access of the user who starts it, and in OpenCode 2 every tool runs inside a background server owned by that user. An account without sudo limits what the agent can reach. Create a coder user and copy your SSH key to it:

sudo useradd --create-home --shell /bin/bash coder
sudo install -d -m 700 -o coder -g coder /home/coder/.ssh
sudo install -m 600 -o coder -g coder ~/.ssh/authorized_keys /home/coder/.ssh/authorized_keys

Log in as coder from a new terminal on your computer:

ssh coder@YOUR_SERVER_IP

Replace YOUR_SERVER_IP with the server's address, such as 203.0.113.10. Steps 3 to 6 run in this session.

Step 3: Install OpenCode

Run the official installer:

curl -fsSL https://opencode.ai/v2/install | bash

The script places the binary in ~/.opencode/bin and adds that directory to PATH in ~/.bashrc. To pin the version checked here, append -s -- --version 2.0.22 after bash. The older address, https://opencode.ai/install, installs the 1.x line.

Reload the shell and check the version:

source ~/.bashrc
opencode --version

The output shows 2.0.22 or a newer version.

Step 4: Add your OpenCode API key

Open the provider picker:

opencode auth login

Pick OpenRouter, Anthropic or OpenAI and paste your API key. For a ChatGPT Plus or Pro account, pick OpenAI and its headless login, which prints a link to open on your own computer. OpenCode stores the key in ~/.local/share/opencode/opencode.db, so it stays out of shell history.

List the models available with that key:

opencode models | grep -i openrouter

Replace openrouter with anthropic or openai to match your provider. Copy a model ID in provider/model form, such as openrouter/anthropic/claude-sonnet-5.5.

Step 5: Set the default model and sandbox permissions

OpenCode 2 allows every tool by default and asks only before reading .env files or paths outside the project. Set your model and make shell commands ask first. Replace YOUR_PROVIDER/YOUR_MODEL with the ID from Step 4 before you run the block:

mkdir -p ~/.config/opencode
tee ~/.config/opencode/opencode.json > /dev/null <<'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "model": "YOUR_PROVIDER/YOUR_MODEL",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git log *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "shell", "resource": "sudo *", "effect": "deny" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" }
  ]
}
EOF
opencode service restart

The restart loads the new rules into the background server, which may already be running from Step 4. The last matching rule wins, so the exceptions follow the broad shell rule. When a command hits an ask rule, OpenCode offers Allow once, Allow always or Reject, and a deny rule overrides any saved approval.

Step 6: Start OpenCode in a tmux session

For a private repository, first create a key as coder with ssh-keygen -t ed25519, print it with cat ~/.ssh/id_ed25519.pub, and add it as a deploy key on that one repository. Then clone the repository (with its SSH URL if it is private) and open a named tmux session in it:

mkdir -p ~/projects
git clone YOUR_REPO_URL ~/projects/YOUR_REPO
tmux new -s opencode -c ~/projects/YOUR_REPO

Start OpenCode inside tmux:

opencode

Shift+Tab cycles between the Build agent, which edits files, and the Plan agent, which explores and plans without editing project files. Shell commands in both follow your permission rules. /models changes the model and /undo reverts your last message and the work that followed it. Detach with Ctrl+B, then D. The session keeps running after SSH closes. Reattach on your next login as coder:

tmux attach -t opencode

Use the web UI over an SSH tunnel

The same background server serves a password-protected web UI on 127.0.0.1 port 49374. Forward the port from your computer, then run opencode pair in that SSH session:

ssh -L 49374:127.0.0.1:49374 coder@YOUR_SERVER_IP

Open the printed http://127.0.0.1:49374/auth/connect/... link in your local browser within 5 minutes. Each link works once. Leave the service hostname at 127.0.0.1 so the web UI stays reachable only through SSH.

Step 7: Connect OpenCode to a local Ollama model (optional)

Run the commands through ollama pull as your sudo user in a separate SSH session. How to Install Ollama on Ubuntu 24.04 covers the full setup.

curl -fsSL https://ollama.com/install.sh | sh

The script installs the ollama systemd service on 127.0.0.1:11434. Ollama gives models a 4,096-token context on servers without a GPU, and OpenCode needs at least 64,000 tokens. Raise it with a systemd override. If you followed the Ollama tutorial, change only OLLAMA_CONTEXT_LENGTH to 64000 in the existing override.conf and run the last two commands:

sudo mkdir -p /etc/systemd/system/ollama.service.d
sudo tee /etc/systemd/system/ollama.service.d/override.conf > /dev/null <<'EOF'
[Service]
Environment="OLLAMA_HOST=127.0.0.1:11434"
Environment="OLLAMA_CONTEXT_LENGTH=64000"
EOF
sudo systemctl daemon-reload
sudo systemctl restart ollama

OLLAMA_HOST keeps the API on the loopback address.

Pull a model with tool support that fits your RAM. Best Ollama Models for CPU Servers lists the RAM each model needs. On 16 GB:

ollama pull qwen3.5:9b

On 32 GB, pull qwen3.6:35b-a3b-q4_K_M instead.

These figures come from the CPU benchmark in Self-Hosted LLM on a VPS, measured with Ollama 0.32.15 on a High Performance hvm.xlarge plan (16 vCPU, 32 GB RAM, no GPU):

With Qwen3.5 9B, the first output token arrived after 53.36 seconds on the 8K prompt, and OpenCode prompts grow as a session adds files. Fewer vCPU or a lower-clocked processor means fewer tokens per second. The same benchmark measured a Qwen3.5 9B peak of 8.09 GiB RAM with a 32K prompt and 11.24 GiB in a 128K test. For Qwen3.6 35B-A3B, check the SIZE column in ollama ps after the first request.

Use the local model for interactive sessions: a request loads the CPU for seconds to minutes, and Ollama unloads the model after 5 idle minutes. Sustained full-CPU load is not permitted on Arct plans, so run continuous or batch generation, including scripted opencode run jobs, on an API model.

OpenCode 2 probes Ollama at 127.0.0.1:11434 without a config entry. As coder, restart the background server and list the models:

opencode service restart
opencode models | grep -i ollama

Quit OpenCode in tmux with Ctrl+C, start it again, and select the Ollama model with /models.

Step 8: Verify OpenCode is working

Check the version, the background server and the saved provider:

opencode --version
opencode service status
opencode auth list

In the tmux session, ask OpenCode to summarize README.md. A reply that names files from your repository confirms the model connection. Then ask it to run git push --dry-run: the git push * deny rule from Step 5 blocks the command, and OpenCode reports it as denied without contacting the remote.

Update OpenCode

Upgrade the binary and restart the background server so it runs the new version:

opencode upgrade
opencode service restart

Quit OpenCode in tmux with Ctrl+C and start it again. To update Ollama, run its install script again; the systemd override stays in place.

Troubleshoot common OpenCode errors

FAQ

How do I install OpenCode on Linux?

Run the official installer from opencode.ai/v2/install with curl as a non-root user, then reload the shell and run opencode --version. The script places the binary in ~/.opencode/bin. The older opencode.ai/install address installs OpenCode 1.x.

Is OpenCode free to use?

Yes. OpenCode is free and open source under the MIT License. You pay your model provider for API usage, and local Ollama models cost nothing beyond the server they run on.

Why is OpenCode not working with my Ollama model?

Ollama defaults to a 4,096-token context on servers without a GPU, and OpenCode needs 64,000 tokens or more. Set OLLAMA_CONTEXT_LENGTH to 64000 in the Ollama service and use a model with tool support, such as Qwen3.5 or Qwen3.6.

Which Ollama model works best with OpenCode on a CPU?

Qwen3.6 35B-A3B gave the fastest measured output: 14.24 tokens/s with an 8K prompt on a 16 vCPU High Performance plan, using 22.90 GiB of RAM. Qwen3.5 9B used 7.28 GiB at an 8K context and generated 7.35 tokens/s.

How much RAM does OpenCode need?

Plan for 2 GB of RAM with an API model, the floor this tutorial uses; OpenCode's documentation sets no minimum. A local model adds about 7.3 GiB for Qwen3.5 9B or 22.9 GiB for Qwen3.6 35B-A3B at an 8K context, and more at 64K.

How do I run OpenCode in a sandbox?

Run it as a separate Linux user without sudo, and add permission rules that ask before shell commands. In OpenCode 2, tools run in the background server, so the user account sets the boundary for every command the agent runs.

Does OpenCode keep running after I close SSH?

Yes, when you start it inside tmux. Detach with Ctrl+B then D, close SSH, and reattach later with tmux attach -t opencode. The web UI connects to the same background server through an SSH tunnel.

Next steps

• Best Ollama Models for CPU Servers by RAM Size
• OpenCode permissions documentation

Run OpenCode with an API model on an Arct Cloud General Purpose VPS, or with a local Ollama model on a High Performance VPS. Compare plans.