# Toren > Toren is an open-source, self-hosted durable agent runtime: long-running AI agents on a Postgres event log, in your own cloud. A resumed run never re-pays for a completed model call, and every run can be read afterwards: what it did, what it cost, why it stopped. Toren runs agents as durable, event-sourced processes on Postgres: work measured in hours and days that survives crashes, deploys, and kill -9. Agents can hold conversations (sessions), run autonomously (runs), call tools, delegate to consenting peer agents, and get a sandboxed computer. Deploy locally, on one box with Docker Compose, or into your own AWS account. Website: https://toren.run. Source (Apache-2.0): https://github.com/toren-run/toren. Where it sits: frameworks like LangGraph and CrewAI author agent logic and leave persistence, workers, and deployment to you; durable-execution engines like Temporal, Inngest, and Hatchet make arbitrary code crash-safe and leave the agent layer (model-call replay, compaction, sandboxes, approvals, channels, cost receipts) to you; hosted platforms like Claude Managed Agents and LangGraph Platform run on someone else's cloud; Golem is a durable agent runtime too, on WebAssembly. Toren is the runtime layer with the agent layer built in, on plain Node and your Postgres. ## When to use Toren Reach for Toren when agent work is LONG (hours to days), EXPENSIVE (many model calls whose re-payment on a crash hurts), and UNATTENDED (no human watching who can just re-run): enrichment pipelines, scheduled reports, migrations, document processing, back-office automation, approval-gated actions. Skip it when runs finish in seconds and a retry is free. It is a runtime, not an agent framework: you bring the prompts and tools, Toren makes the execution durable. Everything self-hosts (Postgres locally, your own AWS in production); there is no hosted service, so the HTTP API lives at YOUR deployment's URL, never at toren.run. Quickstart: npx toren-run@latest init my-crew (offline, no API keys needed). Machine-readable API spec: https://toren.run/openapi.json. ## Overview - [Toren documentation](https://toren.run/docs/README.md): Toren is an open-source durable agent runtime: long-running agents in your own cloud. - [FAQ](https://toren.run/docs/faq.md): The questions people ask before trying Toren, answered straight. - [Toren Quickstart](https://toren.run/docs/quickstart.md): From zero to a durable multi-agent run, locally with one dependency, then the identical agent in your own AWS account. ## Guides - [Approvals](https://toren.run/docs/guides/approvals.md): How-to: put a human between an agent and anything irreversible. - [Background runs from chat](https://toren.run/docs/guides/background-runs.md): How-to: ask for a job in conversation, keep chatting, get messaged when it's done. - [Cross-agent calls](https://toren.run/docs/guides/cross-agent-calls.md): One agent delegates a request to another. The peer answers with its own tools and privileges, and shares only the answer. - [Defining agents](https://toren.run/docs/guides/defining-agents.md): How-to: turn a directory of files into a runnable agent. - [AWS reference architecture](https://toren.run/docs/guides/deploy-aws.md): The production posture, in your account: autoscaling workers, RDS, SQS, Secrets Manager, HTTPS via CloudFront. - [Environments](https://toren.run/docs/guides/environments.md): How-to: local, staging, and production without footguns. - [HTTP API](https://toren.run/docs/guides/http-api.md): How-to: trigger runs and read results from anywhere, no VPC access needed. - [Observability](https://toren.run/docs/guides/observability.md): How-to: see what your agents are doing. - [Scheduling](https://toren.run/docs/guides/scheduling.md): How-to: cron-triggered runs that fire exactly once, even through crashes. - [Sessions](https://toren.run/docs/guides/sessions.md): A session is a conversation with an agent that survives anything. - [Workflows & waves](https://toren.run/docs/guides/workflows-and-waves.md): How-to: orchestrate parallel agents and multi-step pipelines. ## Channels - [CLI](https://toren.run/docs/channels/cli.md): The resume line is printed whenever you leave a conversation open. The full transcript replays from the event log, then the prompt is yours again. - [Console](https://toren.run/docs/channels/console.md): The deployment console has a Sessions page: start a conversation with any agent, watch it think, send the next turn when it yields, and close it when you are done. - [HTTP API](https://toren.run/docs/channels/http-api.md): Turn-taking is strict: sending while the agent is mid-turn returns 409, so wait for awaiting_input. Pass {"close": true} to end the session. - [Channels](https://toren.run/docs/channels/index.md): A channel is any surface where a person talks to your agents. Under every channel sits the same thing: a durable session whose transcript is the event log. - [MCP](https://toren.run/docs/channels/mcp.md): Drive durable runs from the coding agent you already use. - [Telegram](https://toren.run/docs/channels/telegram.md): Each agent that should be reachable on Telegram gets its own BotFather bot and its own bot_token_env. - [WhatsApp](https://toren.run/docs/channels/whatsapp.md): Same model as Telegram: a DM is a durable session, deny-by-default access, one poller elected per deployment, exactly-once turn delivery through the database. ## Tools - [Database (read-only)](https://toren.run/docs/tools/database.md): Set SQL_DATABASE_URL to the database's connection string and the agent gets a sql_query tool: it writes a SELECT, runs it, and gets rows back as JSON. - [Defining tools](https://toren.run/docs/tools/defining-tools.md): The handler returns a string (JSON-encode structured results). - [File parsing](https://toren.run/docs/tools/file-parsing.md): Hand your agents files, not just strings: PDF, Word (docx), Excel (xlsx), and any text format (markdown, CSV, JSON, YAML, HTML, logs). - [Sandbox](https://toren.run/docs/tools/sandbox.md): That grants the toolkit: **bash**, plus **read_file**, **write_file**, and **edit_file** operating on a durable per-run workspace. - [Web search](https://toren.run/docs/tools/web-search.md): That is the whole setup. The loader folds TAVILY_API_KEY into the agent's required env, so a missing key fails fast at startup with a clear message instead of dying mid-run. ## Deploy - [Docker Compose](https://toren.run/docs/deploy/compose.md): The whole runtime on one box: Postgres plus the worker, one file, no cloud account. This is the recommended self-host path. - [Deploying Toren](https://toren.run/docs/deploy/index.md): The same agent directory moves up the ladder unchanged: develop locally, self-host on a box, graduate to the AWS module when you want managed Postgres, queue-backed workers, and a… ## Concepts - [Architecture](https://toren.run/docs/concepts/architecture.md): Explanation, the shape of the system and why it's shaped that way. - [Durability & replay](https://toren.run/docs/concepts/durability.md): Explanation, why a toren run survives anything, and why resumes are free. ## Reference - [agent.yaml reference](https://toren.run/docs/reference/agent-yaml.md): Planned keys (planned, not yet implemented, will fail silently today, don't set them): fallbacks, runtime: short|long, sandbox.snapshotEvery, limits.maxWaves, limits.maxBudgetUsd. - [CLI reference](https://toren.run/docs/reference/cli.md): All commands take --json for machine-readable output where applicable. DATABASE_URL selects the Postgres instance (default postgres://toren:toren@localhost:5433/toren); - [Client SDK reference](https://toren.run/docs/reference/client.md): @toren-run/client is a typed, zero-dependency client for the HTTP API (global fetch; inject your own via config for tests). Response shapes mirror the server exactly; - [Event catalog reference](https://toren.run/docs/reference/events.md): Every run is two-plus append-only streams in the agent's schema: run (written by the orchestrator holding the run lease) and task: (written by that task's lease holder). - [Host API reference](https://toren.run/docs/reference/host-api.md): @toren-run/core as a library: embed the runtime in your own process instead of using the CLI. This is the surface the CLI itself is built on; - [Model providers](https://toren.run/docs/reference/providers.md): The model key in agent.yaml routes by prefix. Each subagent may use a different model, so one crew can mix providers freely. - [Versioning & compatibility](https://toren.run/docs/reference/versioning.md): Toren is pre-1.0 and says so; this page is the contract that makes upgrading boring anyway. - [Workflow API reference](https://toren.run/docs/reference/workflow-api.md): A workflow is a default-exported (ctx: WorkflowCtx) => Promise.