AgentOS is an open-source runtime for AI agents — providing sandboxed execution, persistent storage, and tool orchestration. Built by engineers who believe software should be designed for LLMs.
Latest essays on AI infrastructure, architecture, and engineering
Thinking in public about AI infrastructure, software architecture, and what comes next
Everything you need to build, deploy, and manage AI agents on AgentOS. This guide covers the SDK, CLI, and core platform concepts.
Install the AgentOS SDK via npm. The package includes the client library, TypeScript definitions, and the CLI.
npm install @agentos/sdkOr with yarn:
yarn add @agentos/sdkVerify installation:
npx agentos --version
# agentos-sdk v2.4.1Create your first agent in under a minute. The following example initializes a runtime, registers a simple tool, and executes a task:
import { AgentOS } from "@agentos/sdk";
const agentos = new AgentOS({
apiKey: process.env.AGENTOS_API_KEY,
region: "us-east-1",
});
// Create an agent with a system prompt
const agent = await agentos.agent.create({
name: "research-assistant",
model: "claude-sonnet-4-20250514",
systemPrompt: "You are a helpful research assistant.",
tools: ["web-search", "file-read"],
sandbox: { memory: "512mb", timeout: 30000 },
});
// Execute a task
const result = await agent.run("Summarize the latest papers on RLHF.");
console.log(result.output);All API requests require a valid API key. Generate one from the AgentOS dashboard at app.agentos.dev/dashboard or via the CLI:
agentos auth login
# Opens browser for OAuth flow
# Or set directly via environment variable
export AGENTOS_API_KEY="cos_live_..."For CI/CD environments, use service account tokens:
agentos auth create-service-account \
--name "deploy-bot" \
--scopes "agent:write,storage:read"cos_test_ operate in sandbox mode and do not incur charges.
The Agent Runtime is the core execution environment for AI agents on AgentOS. Each agent runs as an isolated process with its own context, tools, and resource limits. The runtime manages the observe-plan-execute loop, handling tool dispatch, error recovery, and state persistence automatically.
Agents can be ephemeral (single task, tear down after completion) or persistent (long-running, maintaining state across invocations). Persistent agents retain their conversation history, file system state, and registered tools between sessions.
// Ephemeral agent — runs once, then deallocated
const ephemeral = await agentos.agent.create({
name: "one-shot-coder",
ephemeral: true,
sandbox: { timeout: 60000 },
});
// Persistent agent — retains state across calls
const persistent = await agentos.agent.create({
name: "project-assistant",
ephemeral: false,
storage: { volumeSize: "1gb" },
});Every agent runs inside a sandboxed environment with strict resource isolation. Sandboxes provide:
Sandboxes boot in under 200ms (cold start) and support checkpointing for instant resume.
AgentOS provides a durable key-value and file storage layer that persists across agent sessions. Storage is scoped per-agent by default, with optional shared namespaces for multi-agent workflows.
// Write structured data
await agentos.storage.write("/config/preferences.json", {
theme: "dark",
language: "en",
});
// Read it back
const prefs = await agentos.storage.read("/config/preferences.json");
console.log(prefs.theme); // "dark"
// List directory contents
const files = await agentos.storage.list("/config/");Tools are the primary interface between agents and external capabilities. AgentOS provides a registry for declaring tools with typed schemas, and the runtime handles dispatch, validation, and error propagation.
// Register a custom tool
agentos.tools.register("fetch-weather", {
description: "Get current weather for a location",
parameters: {
type: "object",
properties: {
location: { type: "string", description: "City name or coordinates" },
units: { type: "string", enum: ["celsius", "fahrenheit"] },
},
required: ["location"],
},
handler: async ({ location, units }) => {
const resp = await fetch(
`https://api.weather.example.com/v1/current?q=${location}&units=${units}`
);
return resp.json();
},
});The AgentOS SDK exposes a consistent async API. All methods return Promises and support both callback and async/await patterns.
Create and initialize a new agent instance with the given configuration.
name string — unique identifier for the agentmodel string — model ID (e.g. "claude-sonnet-4-20250514")systemPrompt string — instructions defining agent behaviortools string[] — list of registered tool names to enablesandbox object — resource limits: memory, timeout, cpuephemeral boolean — if true, agent is destroyed after task completion (default: true)Returns: Promise<Agent>
Read data from persistent storage at the specified path.
path string — storage path (e.g. "/data/results.json")Returns: Promise<any> — parsed content, or null if path does not exist
Write data to persistent storage. Overwrites existing content at the path.
path string — storage pathdata any — data to store (serialized as JSON for objects)Returns: Promise<{ bytesWritten: number, etag: string }>
Register a custom tool that agents can invoke during execution.
name string — tool identifier (alphanumeric, hyphens allowed)handler object — tool definition including description, parameters (JSON Schema), and handler functionReturns: void
Execute arbitrary code in the agent's sandboxed environment.
code string — code to execute (JavaScript/TypeScript by default)Returns: Promise<{ stdout: string, stderr: string, exitCode: number }>
const result = await agentos.sandbox.exec(`
const resp = await fetch("https://api.agentos.dev/v2/health");
console.log(resp.status);
`);
console.log(result.stdout); // "200"The AgentOS CLI provides project scaffolding, deployment, and observability commands. Install globally with npm install -g @agentos/sdk.
agentos init
Initialize a new AgentOS project in the current directory. Creates agentos.config.json, sets up directory structure, and installs dependencies.
$ agentos init
? Project name: my-agent
? Template: minimal | full | typescript
? Region: us-east-1
Creating project structure...
agentos.config.json
src/agent.ts
src/tools/
.env.example
Done. Run `agentos deploy` to publish.agentos deploy
Build and deploy the current project to AgentOS. Bundles source, uploads assets, and provisions agent runtime.
$ agentos deploy
Bundling agent... done (1.2s)
Uploading to us-east-1... done
Provisioning sandbox... done
Agent deployed: https://agentos.dev/agents/my-agent
Live in 3.4sagentos logs
Stream real-time logs from a deployed agent. Supports filtering by level and time range.
$ agentos logs --agent my-agent --follow
2026-03-22T10:14:02Z [info] Agent started (pid: 4821)
2026-03-22T10:14:02Z [info] Tools loaded: web-search, file-read
2026-03-22T10:14:03Z [info] Task received: "Summarize latest RLHF papers"
2026-03-22T10:14:05Z [debug] Tool call: web-search("RLHF 2026 papers")
2026-03-22T10:14:08Z [info] Task completed (5.1s, 2 tool calls)agentos logs --level error to filter for errors only, or agentos logs --since 1h to view the last hour of activity.
Error: AGENT_AUTH_FAILED (403) — Your API token may have expired or your agent's IP is not allowlisted. Regenerate your token at app.agentos.dev/auth/tokens and update your configuration.
Error: SANDBOX_TIMEOUT (504) — The sandbox exceeded the configured execution timeout. Check deployment logs at app.agentos.dev/logs or increase spec.resources.timeout.
Error: STORAGE_QUOTA_EXCEEDED (507) — Your agent has exceeded its storage allocation. View usage at app.agentos.dev/storage/usage and consider upgrading your plan or cleaning up unused volumes.
For additional help, see our community forums or check the service status page.
An anonymous engineering team building open infrastructure for AI agents.
Software is entering its most significant inflection point since the advent of the internet. Large language models are not just tools — they are a new class of software consumer. The APIs we build, the systems we design, and the infrastructure we operate will increasingly serve autonomous agents alongside human users.
We believe this transition demands new primitives. Not wrappers around existing cloud services, but purpose-built runtimes that treat AI agents as first-class citizens: with sandboxed execution environments, durable state, and composable tool interfaces.
Every component of AgentOS is open source. We believe infrastructure this fundamental should be collectively owned.
Our APIs are designed for LLM consumption first. If a model can't use it in one shot, the interface is wrong.
We resist framework sprawl. The best agent infrastructure is the thinnest layer that still provides safety and observability.
Sandboxing isn't an afterthought. Every agent runs in isolation, with explicit capability grants and full audit trails.
AgentOS is built by a small, anonymous engineering team distributed across multiple time zones. We've collectively spent decades building infrastructure at scale — cloud platforms, distributed systems, developer tools — and we've converged on the conviction that AI agents need better foundations.
We don't chase hype cycles. We ship infrastructure. The kind of boring, reliable, well-documented software that other people build interesting things on top of.
We're always interested in hearing from engineers working on agent infrastructure. Whether you want to contribute, report a bug, or just talk shop: