Agents

Claude Code

Run the Claude Code agent inside a VM with skills, MCP servers, and custom configuration.

Quick start

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

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

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

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

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

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

LLM Credentials

Set the relevant variable(s) on the session’s env, sourced from your server’s environment:

ANTHROPIC_API_KEY — Anthropic API key (direct API).
ANTHROPIC_AUTH_TOKEN — bearer token for proxy / OAuth auth.
ANTHROPIC_BASE_URL — route through a gateway or proxy endpoint.
ANTHROPIC_MODEL — override the default model.
CLAUDE_CODE_USE_BEDROCK=1 — use Amazon Bedrock (auth via the AWS credential chain: AWS_REGION, AWS_PROFILE, …).
CLAUDE_CODE_USE_VERTEX=1 — use Google Vertex AI (auth via Google Cloud credentials).

See LLM Credentials, and Claude Code’s environment variables for the full list.

Skills

Claude Code discovers agent skills from SKILL.md files under its skills directory. Write the skill into the VM before creating a session and Claude Code 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/.claude/skills/commit-style");
  await agent.writeFile("/home/agentos/.claude/skills/commit-style/SKILL.md", skill);

  // Claude Code discovers the skill automatically
  const sessionId = await agent.createSession("claude", {
    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 mcpConfig = {
  mcpServers: {
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/agentos"],
    },
    remote: {
      type: "sse",
      url: "https://mcp.example.com/sse",
      headers: { Authorization: "Bearer my-token" },
    },
  },
};
await agent.writeFile("/home/agentos/.claude.json", JSON.stringify(mcpConfig));

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

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

Claude Code 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.