OpenCode

OpenCode is a terminal coding assistant. VirtuAI can appear in it as a model provider. You don’t pick a raw model: you pick one of your VirtuAI agents, and its system prompt, model and tools stay as you set them in VirtuAI.

The agent runs on VirtuAI. When it wants to read a file, edit code or run a command, OpenCode does that on your machine, in the folder you opened. VirtuAI never reads your disk directly.

Before you start

• OpenCode installed
• The VirtuAI CLI, paired with your workspace. See VirtuAI CLI.
• At least one agent with Web Chatbot on and Harness set to Deep in Deep Agent Mode. Only these agents are offered to OpenCode.

Set up

1. Update the CLI and pair it, if you haven’t:

   pipx upgrade virtuai-cli
   virtuai pair <CODE> --server https://<your-virtuai-host>

2. Connect OpenCode:

   virtuai opencode

   This adds a virtuai provider to ~/.config/opencode/opencode.json, lists your agents as its models, and maps OpenCode’s build and plan slots to your Build and Plan agents. Your other providers, plugins and MCP servers are left alone.

3. Check the workspace and credential lines it prints. They tell you which workspace’s agents you got.

4. Restart OpenCode if it was running.

Run virtuai opencode again whenever you add or rename agents, then restart OpenCode.

Day to day

1. cd into your project and start OpenCode.
2. Pick a VirtuAI agent as the model, or use the build and plan agents.
3. Work as usual. The agent knows your working folder and whether it’s a Git repository.

Agent	What it can do on your disk
Plan, and any agent marked read-only	Read and search only. VirtuAI enforces this, whatever OpenCode allows.
Build and other agents	Read, search, edit files and run commands

Each OpenCode session has its own conversation with each agent. When you switch from Plan to Build in a session, Build starts with the plan in view, so you can just say “Proceed”. That only happens the first time Build is used in the session. If you go back and change the plan, tell Build to re-read it.

Permissions

Keep bash and edit allowed for Build in OpenCode. If OpenCode denies them, the agent can’t change anything.

Caution

There are no approval prompts in this setup. Commands run as soon as the agent asks for them, as your user. Use it the way you’d use a powerful local shell, and only in folders you’re comfortable with.

Cost and context

• The dollar amount OpenCode shows is its own estimate, and it reads low. Your workspace budgets and usage in VirtuAI are the real figures.
• VirtuAI compacts the conversation itself when it nears the model’s limit, so OpenCode’s automatic compaction is turned off. The context bar can drop on its own when that happens. /compact still works.

Keep the token safe

OpenCode can’t read your system keychain, so virtuai opencode writes a copy of your CLI token into opencode.json, readable only by you. Treat that file like a password: don’t commit it or share it.

virtuai unpair doesn’t remove that copy. Delete the provider.virtuai block from opencode.json yourself.

Troubleshooting

The model list is empty : Only agents with Web Chatbot on and the Deep harness are listed. Also run virtuai status to check the server and workspace.

Agents from the wrong workspace : The workspace comes with your credential. virtuai opencode tries your pairing token first, then your login token. Pair again from the workspace you want, then run virtuai opencode.

401 errors out of nowhere : Someone paired another machine to the workspace, which replaces the token. Run virtuai pair <CODE>, then virtuai opencode, and restart OpenCode.

The agent says it can’t edit or write files : OpenCode swaps its edit tools when the model ID contains gpt-. Your model IDs are agent IDs, so rename the agent.

New agents don’t show up : Run virtuai opencode again and restart OpenCode.