> ## Documentation Index
> Fetch the complete documentation index at: https://polos.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Welcome to Polos

> The open-source runtime for AI agents

# Introduction

**Building agents is easy. Running them in production is hard.**

Polos handles sandboxes, durability, approvals, triggers, and observability - so you can focus on writing the agent.
No DAGs. No graph syntax. Just Python or TypeScript.

<CodeGroup>
  ```python Python theme={null}
  from polos import Agent, sandbox_tools, SandboxToolsConfig, DockerConfig

  # Create a sandboxed environment - agents get exec, read, write,
  # edit, glob, and grep tools automatically.
  sandbox = sandbox_tools(SandboxToolsConfig(
      env="docker",
      docker=DockerConfig(image="node:20-slim", memory="2g"),
  ))

  # Give the agent sandbox tools - it can now run commands,
  # read/write files, and explore the codebase autonomously.
  coding_agent = Agent(
      id="coding_agent",
      provider="anthropic",
      model="claude-sonnet-4-5",
      system_prompt="You are a coding assistant. The repo is at /workspace.",
      tools=sandbox,  # exec, read, write, edit, glob, grep
  )
  ```

  ```typescript TypeScript theme={null}
  import { defineAgent, sandboxTools } from '@polos/sdk';
  import { anthropic } from '@ai-sdk/anthropic';

  // Create a sandboxed environment - agents get exec, read, write,
  // edit, glob, and grep tools automatically.
  const sandbox = sandboxTools({
    env: 'docker',
    docker: {
      image: 'node:20-slim',
      memory: '2g',
    },
  });

  // Give the agent sandbox tools - it can now run commands,
  // read/write files, and explore the codebase autonomously.
  const codingAgent = defineAgent({
    id: 'coding_agent',
    model: anthropic('claude-sonnet-4-5'),
    systemPrompt: 'You are a coding assistant. The repo is at /workspace.',
    tools: [...sandbox], // exec, read, write, edit, glob, grep
  });
  ```
</CodeGroup>

## Polos vs. Typical Agent Frameworks

| Challenge         | Typical agent framework              | With Polos                                                              |
| ----------------- | ------------------------------------ | ----------------------------------------------------------------------- |
| **Sandboxing**    | None - DIY or run unsandboxed        | Docker, E2B + built-in tools (exec, files, search)                      |
| **Durability**    | Agent crashes, start over            | Auto-retry, resume from exact step                                      |
| **Approvals**     | Build it yourself                    | Slack, UI, terminal - one tap                                           |
| **Slack**         | Build a bot from scratch             | [@mention an agent](/agents/slack-integration), get responses in-thread |
| **Triggers**      | Glue code for every webhook          | Built-in: HTTP, webhooks, cron, events                                  |
| **Observability** | Grep through logs                    | Full tracing, every tool call, every decision                           |
| **Cost**          | Re-run failed LLM calls from scratch | Durable execution, prompt caching, 60-80% savings                       |

## What You Get With Polos

* **[Sandboxed Execution](/agents/sandbox)** - Isolated Docker and E2B environments. Built-in tools: exec, read, write, edit, glob, grep, web\_search. No tool code to write, no sandbox lifecycle to manage.
* **[Human-in-the-Loop](/agents/human-in-the-loop)** - Approval flows for any tool call. Reach your team via Slack, Discord, email. Paused agents consume zero compute.
* **[Durable Workflows](/fundamentals/durable-execution)** - Auto-retry, log-replay, concurrency control. Resume from the exact step that failed. 60-80% cost savings via prompt caching.
* **[Slack Integration](/agents/slack-integration)** - @mention your bot to trigger any agent. Responses stream back to the thread. Tool approvals show up as Approve/Reject buttons in Slack.
* **[Triggers](/workflows/event-triggered-workflows)** - Webhook URLs, HTTP API, cron schedules, event-driven.
* **[Observability](/observability/tracing)** - OpenTelemetry tracing for every step, tool call, and approval. Full execution history. Visual dashboard for monitoring and debugging.
* **Bring Your Stack** - Any LLM via Vercel AI SDK and LiteLLM. CrewAI, LangGraph, and Mastra compatible. Python or TypeScript. Open source - run anywhere.

### CLI and UI to monitor and run your agents

```bash theme={null}
polos dev                    # Start server + worker with hot reload
polos run <agent>            # Start an interactive session with an agent
polos agent list             # List available agents
polos tool list              # List available tools
polos logs <agent>           # Stream logs from agent runs
```

<Frame>
  <img src="https://mintcdn.com/gypsumaiinc/5gs21id7AAZHDz6i/images/weather-agent-trace.png?fit=max&auto=format&n=5gs21id7AAZHDz6i&q=85&s=05469250e43fa5709a08b76ac9ccbf8a" alt="Polos observability dashboard showing agent traces" width="3002" height="1550" data-path="images/weather-agent-trace.png" />
</Frame>

## See It in Action

Watch a coding agent built with Polos - sandboxed execution, tool approvals, and real-time observability.

<iframe src="https://www.youtube.com/embed/KYVBpdZ_5eM?start=1&rel=0" width="100%" height="450" frameborder="0" title="Polos Demo" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen />

## What Can You Build?

* **[Coding Agent](/guides/18-sandbox-tools)** - Clones repos, writes code, runs tests, and opens PRs - all inside a Docker sandbox with human approval before anything ships.
* **[Data Analyst](/guides/22-approval-page)** - Connects to data warehouses, executes SQL in sandboxed environments, builds charts, sends approval pages before sharing with stakeholders.
* **[Research Agent](/guides/20-web-search-agent)** - Crawls multiple sources, extracts findings, builds knowledge bases. Durable execution checkpoints after each source. Notifies via Slack or Discord.
* **[Order Processing](/guides/17-order-processing)** - Handles incoming orders, runs fraud checks, suspends for human review on flagged transactions. Exactly-once execution guarantees no double charges.
* **[Scheduled Workflows](/guides/16-scheduled-workflows)** - Cron-triggered agents that run nightly data syncs, generate reports, or clean up stale resources. Durable state means missed runs pick up where they left off.

## Next Steps

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Build and run a sandboxed coding agent in minutes
  </Card>

  <Card title="Core Concepts" icon="lightbulb" href="/fundamentals/overview">
    Learn how Polos handles state and durability
  </Card>

  <Card title="Examples" icon="book-open" href="/guides/cookbook-examples">
    See how to build HITL agents and multi-agent systems
  </Card>
</CardGroup>

<Note>
  Polos is 100% open source. [Star us on GitHub](https://github.com/polos-dev/polos) if you find it useful, and [join our Discord](https://discord.gg/ZAxHKMPwFG) to connect with the community.
</Note>