# Codex

## Quick start

server.ts:

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

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

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

client.ts:

```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");

// ── Quick start ───────────────────────────────────────────────────
async function quickStart() {
	await agent.sessions.open({
		agent: "codex",
		env: { OPENAI_API_KEY: process.env.OPENAI_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](/agentos/docs/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:

- `OPENAI_API_KEY` — OpenAI API key (built-in `openai` provider).
- `OPENAI_BASE_URL` — route through a gateway or OpenAI-compatible endpoint.
- Custom providers — defined in `~/.codex/config.toml`; each provider's `env_key` names the variable Codex reads for its key (e.g. `AZURE_OPENAI_API_KEY`, `MISTRAL_API_KEY`).

See [Models & Credentials](/agentos/docs/models-and-credentials), and Codex's [config reference](https://developers.openai.com/codex/config-reference) for details.

## Skills

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

examples/codex/client.ts:

```ts
// ── Skills ────────────────────────────────────────────────────────
//
// Write a SKILL.md into the agent's skills directory before creating the
// session and the agent discovers it automatically.
async function withSkill() {
	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.
`;

	await agent.filesystem.mkdir("/home/agentos/.codex/skills/commit-style");
	await agent.filesystem.writeFile(
		"/home/agentos/.codex/skills/commit-style/SKILL.md",
		skill,
	);

	await agent.sessions.open({
		agent: "codex",
		env: { OPENAI_API_KEY: process.env.OPENAI_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.

examples/codex/client.ts:

```ts
// ── MCP servers ───────────────────────────────────────────────────
//
// Codex reads MCP servers from its own config file. Write a `config.toml`
// into the VM before creating the session — local child-process servers and
// remote URLs are both supported.
async function withMcp() {
	// Pre-install the MCP server so `npx` is silent — first-run install output
	// would otherwise corrupt the MCP stdio handshake ("Connection closed").
	await agent.process.exec("npm install -g @modelcontextprotocol/server-filesystem");

	const config = `[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/agentos"]

[mcp_servers.example]
url = "https://mcp.example.com/sse"
http_headers = { Authorization = "Bearer my-token" }
`;

	await agent.filesystem.writeFile("/home/agentos/.codex/config.toml", config);

	await agent.sessions.open({
		agent: "codex",
		env: { OPENAI_API_KEY: process.env.OPENAI_API_KEY! },
	});
}
```

> **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.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

Codex 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](/agentos/docs/agents/custom).