VPS Tutorials
OpenCode Web on a VPS: SSH, Passwords and Caddy HTTPS (2026)
Install OpenCode as a dedicated Ubuntu user, authenticate its model provider, run a persistent password-protected service, connect through SSH or HTTPS, and verify permissions, updates and recovery.

Running OpenCode Web on a VPS lets you continue working from a browser while keeping the repository and provider credentials on the remote machine. Three things need deliberate setup: a persistent service, a protected browser connection, and the files/commands available to the coding agent. This guide uses one developer on an Ubuntu VPS, first through SSH and then, optionally, Caddy HTTPS.
OpenCode is an open-source coding agent with a browser interface. A local server without an access password is not protected by default. Keep it listening on 127.0.0.1:4096 and reach it through SSH or a proxy; do not publish 4096 directly.
The configured model provider handles inference. The VPS runs repository search, commands, dependencies and builds; installing OpenCode does not install a local large model. For a small repository, 2 vCPU, 4 GB RAM and 20 GB free disk is a trial planning point, not an official minimum or performance guarantee. Large Node builds, tests and parallel jobs need measured headroom. Check free -h and df -h, including space for artifacts and logs.
Use a dedicated ordinary user and its own workspace. Do not run the agent as root or put production database credentials, cloud keys or the host Docker socket within casual reach. The Web password controls entry, not the agent's Linux permissions. Untrusted repositories or separate users require stronger isolation, such as independent VPSs or carefully restricted containers.
Prepare Ubuntu 24.04/26.04, working SSH and a supported provider credential. Installation assumes the current administrator has sudo; a domain is needed only for HTTPS browser access.
Install tools and create a user outside the sudo group. Skip adduser if it already exists and verify home directory /home/agent:
sudo apt update
sudo apt install -y curl git openssl
sudo adduser --disabled-password --gecos '' agent
sudo -iu agent
mkdir -p ~/workspaces
curl -fsSL https://opencode.ai/install | bash
~/.opencode/bin/opencode --version
The official installer places the binary in ~/.opencode/bin/. Review the installation source before executing it. Configure credentials in the agent user's session:
~/.opencode/bin/opencode auth login
~/.opencode/bin/opencode auth list
auth login selects a provider interactively and records credentials in that user's ~/.local/share/opencode/auth.json. Keep API keys out of repositories, example commands and publicly readable .env files. auth list confirms a stored connection, not available quota or a successful model request; test a small request in the Web interface. See provider configuration for authentication and charging conditions.
Clone/copy the project to ~/workspaces/你的项目 and grant agent the required access. Begin on a test repository with file explanation and a proposed plan before approving changes. Enter exit to return to the administrator's session afterwards.
The Web password is separate from the model API key. Enter the agent account and create a random password in a private environment file:
sudo -iu agent
install -d -m 700 ~/.config
umask 077
printf 'OPENCODE_SERVER_PASSWORD=%s\n' "$(openssl rand -hex 32)" > ~/.config/opencode-web.env
chmod 600 ~/.config/opencode-web.env
cat ~/.config/opencode-web.env
exit
The final command displays the secret; use a private terminal and save it in a password manager, never Git or shared chat. The unit assumes home /home/agent; update all absolute paths if yours differs. Create /etc/systemd/system/opencode-web.service:
[Unit]
Description=OpenCode Web coding agent
Wants=network-online.target
After=network-online.target
[Service]
Type=simple
User=agent
Group=agent
WorkingDirectory=/home/agent/workspaces
Environment=HOME=/home/agent
EnvironmentFile=/home/agent/.config/opencode-web.env
ExecStart=/home/agent/.opencode/bin/opencode web --hostname 127.0.0.1 --port 4096
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
Validate and start:
sudo systemd-analyze verify /etc/systemd/system/opencode-web.service
sudo systemctl daemon-reload
sudo systemctl enable --now opencode-web
sudo systemctl status opencode-web --no-pager
sudo ss -lntp | grep ':4096'
curl -I --max-time 5 http://127.0.0.1:4096/
ss should show 127.0.0.1:4096, and an unauthenticated HTTP request should return 401. This tests authentication, not merely process existence. For a port conflict, find its owner with ss before changing the unit. Do not switch to --hostname 0.0.0.0 for convenience. The Web documentation explains that omitting OPENCODE_SERVER_PASSWORD leaves access unprotected.
On your own computer, forward local 4096 to the VPS loopback address, replacing 你的SSH用户 and VPS_IP:
ssh -N -L 4096:127.0.0.1:4096 你的SSH用户@VPS_IP
Keep the tunnel open and visit http://127.0.0.1:4096. The default username is opencode; use the generated Web password. localhost means your computer, not the VPS. If local 4096 is occupied, change the left-hand port to 14096:127.0.0.1:4096 and open http://127.0.0.1:14096. Verify SSH host identity and a loopback-only local listener. Closing SSH removes browser connectivity while systemd keeps the remote service running.
This uses only your existing SSH entry point. For phone access or a persistent domain, consider HTTPS with access limited to trusted users.
Point A/AAAA for a domain such as agent.example.com to the VPS, allow 80/443 in security groups, and check existing web servers. Keep 4096 private. If needed, use Caddy's Ubuntu installation instructions:
sudo apt install --yes debian-keyring debian-archive-keyring apt-transport-https curl gnupg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy
Add this site to /etc/caddy/Caddyfile rather than overwriting other virtual hosts:
agent.example.com {
reverse_proxy 127.0.0.1:4096
}
Validate and reload:
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://agent.example.com/
With correct DNS and reachable 80/443, Caddy obtains a certificate through automatic HTTPS. The backend remains local and OpenCode still requests Basic Auth. HTTPS is not a login system: keep OPENCODE_SERVER_PASSWORD. A shared endpoint also shares the same Linux user's repositories and provider credentials; deploy separate instances for different permission boundaries. A containerized/remote proxy needs its own private path to the backend, not an assumed shared localhost.
Start with a test repository: explain a file, propose a plan, make one small reviewed change, and inspect git diff. Do not supply production environment files or payment/database secrets. Check the service too:
sudo systemctl is-active opencode-web
sudo journalctl -u opencode-web -n 80 --no-pager
sudo ss -lntp | grep ':4096'
sudo -iu agent /home/agent/.opencode/bin/opencode auth list
Browser unavailable: inspect systemctl status, journalctl and loopback listener 4096. Check the active tunnel, or domain DNS, firewalls, 80/443 and Caddy logs.
Repeated password prompt: use the Web password rather than the provider key. Changes to opencode-web.env require sudo systemctl restart opencode-web.
Interface works, model fails: run auth list for the agent account, then inspect quota, model access and outbound connectivity.
Repository missing or unwritable: inspect paths and agent permissions. Adding sudo is not the fix.
Before updating, back up projects and state under ~/.local/share/opencode/. Run the official installer as agent, check the version and restart. If it fails, stop the service and restore the tested release using backups and version installation options. Keep project Git remotes and independent backups; see snapshots versus backups.
GPU required? No for cloud-provider models. Local inference is a separate hardware/deployment choice.
Expose port 4096 directly? Prefer loopback plus SSH or authenticated HTTPS; retain the Web password in both arrangements.
Does closing the browser stop tasks? It does not stop systemd. Individual tasks depend on their session/process state; inspect the session and Git changes rather than assuming completion.
How does this compare with terminal agents? See Codex CLI remote development and Claude Code on a VPS. This guide specifically covers a persistent, protected OpenCode browser service.