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 "@agentos-software/claude-code";

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

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

await agent.sessions.open({
	agent: "claude",
	env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

const result = await agent.sessions.prompt({
	content: [
		{ type: "text", text: "What files are in the current directory?" },
	],
});
console.log(result.message?.content ?? []);

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

Model & 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 Models & 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.filesystem.mkdir("/home/agentos/.claude/skills/commit-style");
	await agent.filesystem.writeFile(
		"/home/agentos/.claude/skills/commit-style/SKILL.md",
		skill,
	);

	// Claude Code discovers the skill automatically
	await agent.sessions.open({
		agent: "claude",
		env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
	});

MCP servers

Expose extra tools to the agent by passing mcpServers to openSession. 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.filesystem.writeFile(
	"/home/agentos/.claude.json",
	JSON.stringify(mcpConfig),
);

await agent.sessions.open({
	agent: "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.process.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.