F3 Cloud Knowledge Base

English

Русский
Deutsch
Español

English

Русский
Deutsch
Español

OpenCode on a VPS – installing the AI agent, free models and working in the browser

Installing OpenCode 2 on a VPS. Free models with no API key, your first task in the terminal, command confirmation before anything runs, working in the browser over an SSH tunnel, and the opencode pair command. Tested on Debian 12 with OpenCode 2.1.2.

OpenCode is an open-source AI coding agent. You describe a task in plain words, and it reads the project files, writes and edits code, and runs commands in the terminal on its own. You can work with it in the terminal or in the browser. On a server OpenCode is handy because it changes the code right where the project runs, and you can connect to it from any computer. In this article we will install OpenCode on a VPS, give it a first task, set up command confirmation and open it in the browser. We repeated every step on a test server with Debian 12, and the OpenCode version at the time of testing was 2.1.2.

How OpenCode works ​

OpenCode itself is not a neural network. It sends your task to a model together with a description of its tools, and then does whatever the model decided to do. For example, it creates a file, makes an edit or runs a command. The result goes back to the model, and this repeats step by step until the task is done. That is why the quality of the work depends almost entirely on the model you choose.

A nice thing about OpenCode is that it already includes free models. You need no API key and no registration for them, and the agent works right after installation. These models are free for a limited time, and the list changes from time to time. Keep in mind that for some of the free models the collected data may be used to improve the model, and the OpenCode documentation says so directly. The default model, MiniMax M3.1 Flash Free, does not store data and does not use it for training, according to the documentation. For real projects you can connect your own model, for example with an API key from Anthropic, OpenAI or OpenRouter.

In the second version, all sessions, settings and command execution belong to a background service. It starts by itself the first time you run opencode and listens on a port only at the internal address 127.0.0.1, so nobody can connect to it from the internet. The terminal interface and the browser are just windows that connect to this service. That is why a task started in the terminal is visible in the browser too.

By default the agent asks for nothing

We asked OpenCode to install nginx and publish a page on the website. The agent ran apt-get install -y nginx by itself, copied the file to /var/www/html, reloaded nginx and started studying its settings, without asking for permission even once. So install OpenCode on a server that holds no one else's data and no important websites, and turn on command confirmation right after installation, as shown in step 2.

What you will need ​

  • A server with Debian 12 or Ubuntu 24.04 and at least 2 GB of memory, for example the DE-RZ9-1 plan. On our server the OpenCode background service took about 340 MB of memory, and the terminal window another 190 MB or so. If you do not have a server yet, order one by following the guide.
  • An SSH connection, for example through Termius. The commands are run as root.
  • A project folder where the agent will work. In the example it is /root/my-site.

Step 1. Install OpenCode ​

Connect to the server and run the official installation command for the second version.

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

The installer downloads a program of about 200 MB into the /root/.opencode/bin folder and adds it to PATH. To make the opencode command work in the current terminal window, restart the shell.

bash
exec $SHELL
Installing OpenCode 2.1.2 with the official script, with a message about free models

OpenCode is installed, free models are available right away

Why the address has v2

The old command curl -fsSL https://opencode.ai/install | bash installs the first version of OpenCode. Both versions use the opencode command and cannot live side by side, so the installer of the second version replaces the first one. If you already have the first version, its interface will offer to update itself with the /update command.

Step 2. Turn on command confirmation ​

Create the file with the general OpenCode settings.

bash
mkdir -p ~/.config/opencode
nano ~/.config/opencode/opencode.jsonc

Paste the rules below into it and save the file with Ctrl + O, then Enter, and leave the editor with Ctrl + X.

json
{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ]
}
  • The first rule makes the agent ask before every command in the terminal.
  • The second rule makes it ask before working with files outside the project folder. In the second version of OpenCode this access is allowed by default.

To make the service apply the settings, run the command below.

bash
opencode reload

Now before every command the agent shows a Permission required window.

OpenCode asks for permission before running the df -h command, with the buttons Allow once, Always allow and Reject

The agent waits for your permission before running a command

  • Allow once – runs only this command.
  • Always allow – allows it and remembers it for this project. For example, once you allow git status --short, the agent stops asking about all git status commands.
  • Reject – forbids it. The agent stops the task, and you can clarify what needs to be done.

You pick an option with the arrow keys and confirm with the Enter key.

Step 3. Give the agent its first task ​

Go to the project folder and start OpenCode.

bash
cd /root/my-site
opencode

A line for your task appears at the bottom of the screen. Describe the task in your own words and press Enter. We asked it to create a business card page for a coffee shop and check that the file is in place. With a free model the agent finished in 38 seconds.

OpenCode in the terminal created index.html and checked it with the ls -la command, with a report of what was done below

The agent created the page, checked it and described what it did

A few keys and commands will come in handy.

  • Esc interrupts the current task.
  • Ctrl + P opens the list of commands.
  • The /models command opens the model picker. Free models are marked with the word Free.
  • Ctrl + C closes OpenCode. On exit it shows a command like opencode -s ses_…, which brings you back to the same session.
The model picker window in OpenCode with a list of free models

Free models in the /models window

To connect your own model with an API key, type the /connect command in the task line and choose a provider.

You can also give a task without the interface, with a single command. This is handy for scripts.

bash
opencode run "How many lines are in the index.html file?"

Step 4. Open OpenCode in the browser ​

Working with the agent in the browser is more comfortable than in the terminal, especially with long answers and code edits. The OpenCode service is closed off from the internet, so you need to connect to it through an SSH tunnel.

  1. On the server, run the command below. It prints a one-time link like http://127.0.0.1:49374/auth/connect/…. The link works only once and only for 5 minutes.

    bash
    opencode pair

  2. On your own computer, open a new terminal window and create the tunnel. Take the port number from the link, on our server it was 49374.

    bash
    ssh -L 49374:127.0.0.1:49374 root@server-IP

  3. Without closing this window, open the link from the first step in the browser on your computer.

The same OpenCode as in the terminal opens, with all your sessions.

The OpenCode web interface in the browser, where the agent added a table of drinks with prices to the page

OpenCode in the browser through an SSH tunnel

Do not expose the service to the internet

OpenCode has ways to connect without a tunnel, for example the opencode service set hostname 0.0.0.0 command or opencode pair --remote. For the second one, the OpenCode help says outright that the service becomes available from the internet. On a VPS this means that a service which runs commands on your server will be open to the whole world. Use the SSH tunnel.

If the server has rebooted, the OpenCode service does not start by itself. Start it with the opencode service start command or just open opencode in the terminal.

Useful commands ​

bash
opencode                  # open OpenCode in the current folder
opencode -c               # continue the last session
opencode run "task"       # run a task without the interface
opencode models           # list available models
opencode pair             # one-time link for the browser
opencode service status   # address of the background service
opencode service start    # start the service
opencode reload           # reread the settings
opencode upgrade          # update OpenCode
opencode uninstall        # remove OpenCode, sessions and settings are kept

Frequently asked questions ​

opencode: command not found

The current terminal window does not know about the new command yet. Run exec $SHELL or reconnect to the server over SSH.

The link from opencode pair does not open
  1. Check that the window with the SSH tunnel is open and that the ssh -L command uses the same port as the link.
  2. The link works only once and only for 5 minutes. Run opencode pair again and open the new link.
  3. If the port on your computer is busy, forward a different one, for example ssh -L 8080:127.0.0.1:49374 root@server-IP, and replace 49374 with 8080 in the link.
The agent runs commands without asking for permission

This is how OpenCode works by default. Create the ~/.config/opencode/opencode.jsonc file with the rules from step 2 and run opencode reload.

A free model disappeared from the list

Free models are available for a limited time, and OpenCode changes their set from time to time. Open /models and choose another model marked Free, or connect your own with an API key using the /connect command.

Our resources ​

Telegram channel: https://t.me/f3cloud_news
F3 Cloud: https://f3cloud.com