Skip to content
agent.run()

Durability & compute

Keep the work. Choose the compute. AgentRun retains run history and workspace files for recovery, and separates the agent’s reasoning from the machine doing the work.

Execution reference
01 / Durable execution

An interruption shouldn’t erase the work.

A restart can end a process without ending the agent’s run. AgentRun retains the state needed to recover and continue.

  • Recover with contextKeep the conversation, recorded tool results, and workspace together.
  • Keep waiting when input is neededA restart preserves a pending question instead of answering it for you.
  • Run on storage you controlThe retained run directory is the basis for recovery.
A run can outlive its process
Read input
Use tool
Interrupted
Continue
Recover from retained run state
The run stays on diskHistory · recorded results · workspace
SAVED

AgentRun re-adopts a surviving process or reopens the run from saved state.

What recovery preservesRestart behavior, human input, and external actions
Recovery depends on the run’s state
When this happensAgentRun does this
Server restartsRe-adopts a surviving run process. If the process is gone, reopens the run directory and resumes from stored state.
Agent is waiting for a personPreserves the pending question and waits for an answer.
A turn was stoppedA follow-up starts a fresh turn with full history. A cancelled run requires a new run.
A remote workspace is unavailableRecovery depends on the provider and retained files. Data not yet copied back may be unavailable.

Keep the server’s --data directory on persistent storage. The repository’s Compose setup mounts /data in the agentrun-data volume.

External actions are not guaranteed exactly-once. Use idempotency in tools that create side effects. For run creation, AgentRun stores an Idempotency-Key so a retried request returns the same run.

Recovery and run lifecycle
02 / Compute & workspace

Give the agent a computer. Keep its progress.

The harness and model calls run on your server. Commands and file tools run in the selected workspace. AgentRun handles the machine’s lifecycle and brings the work back.

  • One integration across providersUse the same agent and run API when you change the supported sandbox.
  • Separate compute from saved workLocal mounts or remote file sync keep the run’s workspace on retained storage.
  • Configure credentials onceProvider setup belongs on the server, outside the agent’s reasoning loop.
Run state and compute have separate lifetimes
AgentRun serverAgent loop · model calls · run history
Tool callsWorkspace sync
ComputeCommands and toolsCan be replaced
Run directoryState and work filesRetained on your storage
Mount locally or copy changes back

Persist the server’s data directory so recovery has the history and files it needs.

Configure compute for a runCopyable setup and the current server provider contract

Set place on an agent definition. Runs use their pinned revision’s place; a run request cannot override it. The server currently executes sandbox runs on Docker, Daytona, and Modal.

POST /v2/agents — choose a Daytona sandbox
{
  "definition": {
    "id": "researcher",
    "name": "Researcher",
    "instructions": "Analyze input files and save a report.",
    "place": { "mode": "sandbox", "box": "daytona" },
    "tools": ["bash", "read", "write", "edit"],
    "max_cost_usd": 2
  }
}
Agent execution settingsjson
Server environment — enable your providers
AGENTRUN_BOXES=docker,daytona,modal

# Inject credentials through your deployment's secret manager.
DAYTONA_API_KEY=<daytona-key>
MODAL_TOKEN_ID=<modal-token-id>
MODAL_TOKEN_SECRET=<modal-token-secret>
Provider prerequisitesdotenv

Docker needs an accessible daemon and CLI. Modal also needs npm install modal on the server. Restart after configuration and check GET /v2/capabilities for provider readiness. An unavailable provider cannot start a run.

Current server workspace and network behavior
ProviderWorkspaceNetworking
DockerMounts retained work/ at /workspace.Verified domain allowlist, or no network if verification fails.
DaytonaCopies files in; copies changes back at turn end and before completion.Verified domain allowlist, or blocked networking.
ModalCopies files in and changes back to retained work/.Blocked: the current SDK cannot verify the domain policy.

AGENTRUN_BOX_ALLOW replaces the default package-registry and GitHub allowlist; none blocks networking. Modal remains network-blocked. An explicit runner place has no shell, and workflow definitions run on the runner.

Workspace, isolation, and provider details
03 / Open computer protocol

Choose the computer for the job.

Code needs a shell. A desktop task needs a screen. A mobile task needs touch. The Computer protocol gives each kind of machine a consistent set of tools across provider adapters.

  • Match tools to the taskShell and files, screen and input, mobile apps, or browser control.
  • Extend the provider, keep the interfaceAdapters implement the same protocol for their computer kind.
Explore the Computer protocol
Computer protocol · provider adapters
AgentOne computer protocol

Sandbox

Shell · files · processes

Docker · E2B · Daytona · Modal

Desktop

Screen · keyboard · mouse

Docker · E2B · Orgo

Phone

Tap · swipe · app controls

Android phone harness

Browser

Pages · sessions · interaction

Browserbase · Kernel

Broader adapters live in the Computer package, pending its next release and connection to the AgentRun server.

Explore computer kinds and provider adaptersImplemented adapters, extensibility, and server availability

The Computer package on main includes Docker, E2B, Daytona, and Modal sandboxes; Docker, E2B, and Orgo desktops; the Android phone harness; and Browserbase and Kernel browsers. It is a separate package pending its next release and server integration. The current server’s place configuration is the supported setup shown above.

Providers implement a shared lifecycle for creating, attaching, connecting to, and releasing computers. Capabilities describe the tools available to the agent. Adding a provider means implementing the adapter and checking it against the protocol’s conformance tests.

GPU support, iOS, and Windows/macOS desktop providers remain future work.

Computer kinds and tools Provider protocol and conformance
Set up AgentRunRead the documentation