Quickstart

​

Prerequisites

• Node.js 18+
• Python 3.10+ (if building Python agents)
• Postgres database
• An Anthropic API key (or OpenAI / Google)

​

Install Polos

curl -fsSL https://install.polos.dev/install.sh | bash

export PATH="$HOME/.polos/bin:$PATH"

​

Create a project

npx create-polos my-project

pipx run create-polos my-project

✓ Project name: my-project
✓ LLM provider: Anthropic
✓ Done!

​

Configure your API key

cd my-project
cp .env.example .env

ANTHROPIC_API_KEY=sk-ant-...

​

Start the server

polos dev

✓ Polos server started → http://localhost:5173
✓ Worker connected - agents: coding_agent, assistant_agent
Watching for changes...

​

Run an agent

polos run coding_agent

> Build a REST API with Express and SQLite — one endpoint: GET /orders

COMMAND APPROVAL REQUIRED

  The agent wants to run a command:

    Command:   npm init -y && npm install express better-sqlite3
    Directory: /workspace

  Approve this command? (y/n): y

  -> Approved. Resuming...

​

View in the UI

​

Understand the code

​

Project structure

my-project/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   ├── main.ts                          # Worker entry point
│   ├── agents/
│   │   ├── coding-agent.ts              # Coding agent with sandbox tools
│   │   └── assistant-agent.ts           # General-purpose assistant
│   └── workflows/
│       └── text-review/
│           ├── agents.ts                # Specialized review agents
│           └── workflow.ts              # Multi-agent review workflow

my-project/
├── pyproject.toml
├── .env.example
├── src/
│   ├── main.py                          # Worker entry point
│   ├── agents/
│   │   ├── coding_agent.py              # Coding agent with sandbox tools
│   │   └── assistant_agent.py           # General-purpose assistant
│   └── workflows/
│       └── text_review/
│           ├── agents.py                # Specialized review agents
│           └── workflow.py              # Multi-agent review workflow

​

Agent definition

import { anthropic } from '@ai-sdk/anthropic';
import { defineAgent, maxSteps, sandboxTools } from '@polos/sdk';

const tools = sandboxTools({
  env: 'local',
});

export const codingAgent = defineAgent({
  id: 'coding_agent',
  model: anthropic('claude-sonnet-4-5'),
  systemPrompt: 'You are a coding agent with access to sandbox tools. Use your tools to read, write, and execute code.',
  tools,
  stopConditions: [maxSteps({ count: 30 })],
});

from polos import (
    Agent,
    max_steps,
    MaxStepsConfig,
    sandbox_tools,
    SandboxToolsConfig,
)

sandbox = sandbox_tools(
    SandboxToolsConfig(
        env="local",
    )
)

coding_agent = Agent(
    id="coding_agent",
    provider="anthropic",
    model="claude-sonnet-4-5",
    system_prompt=(
        "You are a coding agent with access to sandbox tools. "
        "Use your tools to read, write, and execute code."
    ),
    tools=[*sandbox],
    stop_conditions=[max_steps(MaxStepsConfig(count=30))],
)

• env: "local" runs tools directly on the host - for container isolation in production, use "docker" instead (see Sandbox Tools)
• Exec security defaults to approval-always for local mode - every shell command suspends for your approval
• The agent gets six tools automatically: exec, read, write, edit, glob, grep

​

Worker entry point

import 'dotenv/config';
import { Polos } from '@polos/sdk';

// Import agents and workflows for registration
import './agents/coding-agent.js';
import './agents/assistant-agent.js';
import './workflows/text-review/agents.js';
import './workflows/text-review/workflow.js';

const polos = new Polos();
await polos.serve();

import asyncio
from dotenv import load_dotenv
from polos import Polos

# Import agents and workflows for registration
import agents.coding_agent
import agents.assistant_agent
import workflows.text_review.agents
import workflows.text_review.workflow

load_dotenv()

async def main():
    async with Polos() as polos:
        await polos.serve()

if __name__ == "__main__":
    asyncio.run(main())

​

The Polos CLI

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

​

What just happened?

1. create-polos scaffolded a project with agents, a workflow, and configuration
2. polos dev started the orchestrator, connected your worker, and began watching for changes
3. polos run started an interactive session - the agent decided to write a file, and Polos suspended execution for your approval
4. You approved - Polos resumed execution exactly where it left off
5. The agent ran code in a sandboxed environment with built-in tools
6. Every step was durably checkpointed - if the process crashed mid-execution, it would resume from the last completed step without re-running the LLM calls you already paid for

​

Next steps