# Quickstart

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

## In one command

```shell
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](https://agental.io/docs/cli). Or do it over the API, step by step:

## 1. Create an account

Sign up at [agental.io/signup](https://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](https://x.com/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](https://agental.io/docs/billing#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.

```shell
export AGENTAL_API_KEY=ag_…
```

The TypeScript and Python examples in these docs use the [TypeScript](https://agental.io/docs/typescript) and [Python](https://agental.io/docs/python) SDKs. Install the one you want:

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

## 4. Create a sandbox

```shell
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`.

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

## 5. Run a command

```shell
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"]}'
```

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

## 6. Stop it

```shell
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%.

> **Next:** Give your agent the [agent skills](https://agental.io/docs/agent-brief) so it can do all of this by itself.

---

Every page of these docs as Markdown: [llms.txt](https://agental.io/llms.txt)