OpenCode

Quick start

server.tsclient.ts

server.ts

import { agentOS, setup } from "@rivet-dev/agentos";
import opencode from "@agentos-software/opencode";

const vm = agentOS({ software: [opencode] });

export const registry = setup({ use: { vm } });
registry.start();

client.ts

import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server";

const client = createClient<typeof registry>({ endpoint: "http://localhost:6420" });
const agent = client.vm.getOrCreate("my-agent");

const session = await agent.createSession("opencode", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

const { text } = await agent.sendPrompt(
  session.sessionId,
  "What files are in the current directory?",
);
console.log(text);

Read Sessions first for session options, streaming events, prompts, and lifecycle management.

See Full Example

LLM Credentials

OpenCode auto-detects a provider when its key is present on the session’s env, sourced from your server’s environment. Common variables:

• ANTHROPIC_API_KEY — Anthropic (Claude), the default.
• OPENAI_API_KEY — OpenAI.
• OPENROUTER_API_KEY — OpenRouter.
• GEMINI_API_KEY — Google Gemini.
• GROQ_API_KEY — Groq.
• …plus Amazon Bedrock, Azure, Google Vertex, and 70+ providers via models.dev.

See LLM Credentials, and OpenCode’s providers docs for the full list.

Skills

OpenCode discovers SKILL.md files from its skills directory. Write the skill into the VM before creating a session and OpenCode loads it automatically.

const skill = `---
name: commit-style
description: How to write commit messages in this project.
---

Write commit messages in the imperative mood and keep the subject under 50 characters.
`;

// Write the skill before creating the session
await agent.mkdir("/home/agentos/.config/opencode/skills/commit-style", { recursive: true });
await agent.writeFile("/home/agentos/.config/opencode/skills/commit-style/SKILL.md", skill);

// OpenCode discovers the skill automatically
const session = await agent.createSession("opencode", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

MCP servers

Expose extra tools to the agent by passing mcpServers to createSession. Both local child-process servers and remote URLs are supported.

const session = await agent.createSession("opencode", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  mcpServers: [
    {
      type: "local",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/agentos"],
      env: {},
    },
    {
      type: "remote",
      url: "https://mcp.example.com/sse",
      headers: { Authorization: "Bearer my-token" },
    },
  ],
});

Note

Pre-install npx-launched servers. A local server started with npx -y … writes install progress to stdout on its first run, which corrupts the MCP stdio handshake (you’ll see Connection closed). Pre-install it in the VM so npx is silent — await agent.exec("npm install -g @modelcontextprotocol/server-filesystem") before the session — or pin the package and point command at the installed binary.

Customizing the agent

OpenCode is a built-in agent, but it’s just a software package under the hood. To ship your own ACP adapter, swap the underlying agent SDK, or register a tweaked build as a new agent, see Custom Agents.