Docs
⌘K

Build with agental.

A Linux machine of its own for every agent, over HTTP. Start with four calls, or go straight to a pillar.

Quickstart

  1. 1

    Get an API key

    Make one in the console under Keys, with the preset ci, and put it in AGENTAL_API_KEY.

  2. 2

    Create a sandbox

    A whole Linux machine. Keep its id.

  3. 3

    Run a command

    Anything a shell can run: Docker, a test suite, a browser.

  4. 4

    Stop it

    The disk is kept, at 5% of the running price. Start picks up where it left off.

The quickstart, in full→
curl -X POST https://agental.io/v1/sandboxes \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Idempotency-Key: task-42" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent-1","size":"small"}'

How the API works

Base URL

Every call starts here.

https://agental.io/v1
JSON

Plain HTTP and JSON. Send bodies with Content-Type: application/json.

Errors

Every error has the same shape: {"error":{"code":"...","message":"..."}}. Branch on code.

Exit codes

A command that exits non-zero is still HTTP 200. Read exitCode in the body.

Retries

Creates and forks carry an Idempotency-Key, so retrying them is always safe.

sizes
SizevCPUMemoryDiskPer hour
tiny12 GiB20 GiB$0.0135
small24 GiB40 GiB$0.027
medium48 GiB80 GiB$0.054
large816 GiB160 GiB$0.108

Leave size out to get small. Time is billed by the second: running at the full price, and stopped at 5% of it until the sandbox is deleted. The free plan makes tiny and small sandboxes, the $100 plan makes medium ones too, the $500 plan makes every size, the $2,000 plan makes every size. tiny has one vCPU, so one busy process holds up everything else in it: it suits work that mostly waits, such as an agent calling a model, a bot or a small service. Builds, Docker images and a browser want small or larger.

By pillar

Execution

A shell, a browser and a screen, over HTTP.

Running commandsGitHub ActionsLanguages and toolsFiles

Persistence

Stop it, and the whole disk is kept.

Sandbox lifecycleSnapshotsForkingTemplates and secrets

Connectivity

Ways in for people, mail, and events out.

SSHPublic URLsEmailWebhooks

Observability

What each sandbox uses, and what it costs.

MetricsUsageOpenTelemetryTags and metadata

Security

Keys, allowlists, and no runaway machines.

Outbound rulesAPI keysRetries and idempotencyYour account and data

Tools

API reference →

Every endpoint, its fields and its errors.

GET /v1/sandboxes

TypeScript →

The SDK for Node 20.16 or later.

npm install agental-sdk

Python →

Sync and async clients, Python 3.10 or later.

pip install agental-sdk

Agent skills →

Teach Claude Code, Codex and the others to use sandboxes.

npx skills add https://agental.io -g

Reading this with an agent?

Every page is Markdown too. Hand it llms.txt and it has all of them.

agental.io/llms.txt