Quickstart

From sign-up to your first sandbox: create one, run a command in it, and stop it.

In one command#

npx agental@latest sh

It signs you in through your browser, installs the agental command and the agent skills, and opens a shell in a new sandbox. No key to paste. See Command line. Or do it over the API, step by step:

1. Create an account#

Sign up at agental.io/signup with your email address, GitHub or Google. Sign-ups are invite-only for now, so it asks for an invite code first. No code? Tell Ian what you want to run, on X at @honzabit.

2. Save a card#

Every account starts on the free plan: no monthly fee, and what it runs is paid from credits you top up, at the same rates. Save a card when the console first opens. It is charged nothing, and gives you $10 of credit, once. Or pick a plan from $100 a month on the Pricing page. Until a card is saved or a plan started, a create is refused with 402 billing_required. See the free plan.

3. Get an API key#

Make an API key in the console under Keys, with the preset ci: it makes, forks and starts sandboxes, works in them, and deletes the ones it made. full-sandbox only works in sandboxes that are already there, so it cannot make one. Set the key in your environment. It is shown once.

export AGENTAL_API_KEY=ag_…

The TypeScript and Python examples in these docs use the TypeScript and Python SDKs. Install the one you want:

npm install agental-sdk   # TypeScript, Node 20.16 or later
pip install agental-sdk   # Python 3.10 or later

4. Create a sandbox#

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"}'

The request answers when the machine is ready for commands: in a few seconds when one was made in advance, otherwise usually in under a minute. 201 means created and running. Keep the id.

{
  "id": "sbx_2a9a47e50daec64a",
  "name": "agent-1",
  "size": "small",
  "status": "running",
  "resources": { "vcpu": 2, "memoryMb": 4096, "diskGb": 40 },
  "autoStopAt": null
}

5. Run a command#

curl -X POST https://agental.io/v1/sandboxes/{id}/exec \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":["sh","-c","docker run --rm hello-world"]}'

{
  "exitCode": 0,
  "stdout": "Hello from Docker!\n…",
  "stderr": "",
  "truncated": false
}

6. Stop it#

curl -X POST https://agental.io/v1/sandboxes/{id}/stop \
  -H "Authorization: Bearer $AGENTAL_API_KEY"

The disk is kept, and the meter drops to 5% of the running price. Call POST /v1/sandboxes/{id}/start later to pick up where you left off. Send {"keepMemory":true} with the stop to keep its memory too, and the start puts back every process as it was, at 10%.

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]