Fastest way: the eai CLI
The eai CLI is open source (Apache-2.0) and talks to the same REST API that is described further down. Install it with the install script:
curl -fsSL https://raw.githubusercontent.com/cierrateam/eai-cli/main/install.sh | sh
Or with Homebrew:
brew install cierrateam/tap/eai
Create an account and log in. The free tier needs no credit card.
eai hive signup
eai hive login
Run your first sandbox. Everything after -- is the command that runs inside the sandbox, in its own isolated virtual machine. This one prints 42.
eai hive run python:3.12-slim -- python -c "print(6*7)"
List your sandboxes and delete one by its ID:
eai hive list
eai hive delete <id>
Paid plans
Need more than the free tier? Pro is a monthly subscription from 120 EUR per month (net, plus VAT) with usage credit included, up to 20 concurrent sandboxes, up to 8 vCPU / 16 GB RAM and up to 24 hours runtime per sandbox. Pay as you go uses prepaid credits from 10 EUR, billed per minute. Online checkout is not switched on yet: write to us and we upgrade your account, your CLI login stays the same.
CLI on GitHubOpen source, Apache-2.0
Or use the REST API
Prefer plain HTTP? The following steps do the same with curl. They also work from any HTTP client.
Sign up and verify your e-mail
Create an account in the HIVE portal. We send a confirmation e-mail. Click the link in it to activate your account. The free tier needs no credit card.
Create an API key
Sign in to the portal and create an API key for your team. The key is shown only once. HIVE stores only a hash of it, so copy it into your password manager or secret store right away. If you lose it, create a new key and delete the old one.
Export the key in your shell so the examples below work as written:
export HIVE_API_KEY="paste-your-key-here"
export API="https://hive-api.hive.eai.onl"
Every request carries the key in the header Authorization: Bearer $HIVE_API_KEY.
Create a sandbox
One POST request starts a sandbox from an OCI image. Each sandbox runs in its own isolated virtual machine. This example runs a single Python command and then exits ("restart": "never").
curl -s -X POST "$API/sandbox" \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "python:3.12-slim",
"command": ["python", "-c", "print(6*7)"],
"restart": "never",
"ttl": 600,
"cpu_milli": 1000,
"memory_mi": 1024
}'
The response contains the sandbox ID, its public URL and the expiry time:
{
"sandbox_id": "k3v9x2ab",
"url": "https://k3v9x2ab.hive.eai.onl",
"expires_at": "2026-11-17T10:10:00+00:00",
"restart": "never",
"internet": "full"
}
Keep the ID for the next steps:
export SANDBOX_ID="k3v9x2ab" # use the sandbox_id from your response
Poll the status
The sandbox starts in seconds. Poll until status tells you what you need:
curl -s "$API/sandbox/$SANDBOX_ID" \
-H "Authorization: Bearer $HIVE_API_KEY"
| Field | Meaning |
|---|---|
status | High-level state, for example pending, running, succeeded or failed |
ready | true once the container is up. Useful for services that expose a port |
exit_code | Exit code of your command once it has finished (0 means success) |
expires_at | When the sandbox is removed automatically |
To list all sandboxes of your team, call GET /sandboxes.
Read the logs
Standard output and standard error of your command are available as logs:
curl -s "$API/sandbox/$SANDBOX_ID/logs" \
-H "Authorization: Bearer $HIVE_API_KEY"
# {"logs": "42\n"}
Extend or delete
A sandbox is removed automatically when its TTL expires. If you need it for longer, extend it. The new expiry is the current time plus the given TTL in seconds:
curl -s -X POST "$API/sandbox/$SANDBOX_ID/extend" \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ttl": 600}'
When you are done, delete the sandbox so it no longer counts towards your concurrent sandboxes:
curl -s -X DELETE "$API/sandbox/$SANDBOX_ID" \
-H "Authorization: Bearer $HIVE_API_KEY"
Request options
Fields of the JSON body for POST /sandbox. Only image is required.
| Field | Type | Description |
|---|---|---|
image | string | Any OCI image, for example python:3.12-slim or your own Docker image |
command | list of strings | Command to run instead of the image default |
restart | string | "never" for one-off jobs that run until they exit, "always" for services that should stay up |
ttl | integer | Lifetime in seconds. On the free tier at most 3600 (1 hour) |
cpu_milli | integer | CPU in millicores. 1000 is one vCPU |
memory_mi | integer | Memory in MiB |
port | integer | Port of your service inside the sandbox. It is exposed under the sandbox URL https://<id>.hive.eai.onl |
env | object | Environment variables as key and value strings |
internet | string | "full", "none" or "whitelist". With "whitelist", pass the allowed IP ranges as a list of CIDRs in egress_cidrs |
Example: a small web server that is reachable under its sandbox URL for ten minutes.
curl -s -X POST "$API/sandbox" \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "python:3.12-slim",
"command": ["python", "-m", "http.server", "8000"],
"port": 8000,
"restart": "always",
"ttl": 600,
"internet": "none"
}'
Free tier limits
| Limit | Free tier |
|---|---|
| Sandbox hours | 20 hours per month |
| Concurrent sandboxes | Up to 2 |
| CPU per sandbox | Up to 2 vCPU (cpu_milli ≤ 2000) |
| Memory per sandbox | Up to 2 GB RAM (memory_mi ≤ 2048) |
| Runtime per sandbox | Up to 1 hour per run |
| Outbound e-mail | Ports 25, 465 and 587 are blocked to prevent abuse |
| Credit card | Not required |
The free tier counts sandbox runtime against your monthly hours. Need more? Pro starts at 120 EUR per month with higher limits, Pay as you go at 10 EUR prepaid credit.
Error codes
Errors are returned as JSON with a detail message that says what went wrong.
| HTTP status | Meaning | What to do |
|---|---|---|
401 | Invalid or missing API key | Check the Authorization header and the key |
402 | Free plan limit: monthly hours used up, or more CPU, memory or runtime requested than the plan allows | Lower the request, wait for the next month, or ask us about paid plans |
403 | Account suspended | Contact info@cierra.ai |
422 | Validation error in the request body | Fix the request body. The message names the field |
429 | Too many concurrent sandboxes | Delete a running sandbox or wait until one expires |
503 | no_capacity: no free capacity right now | Try again shortly, ideally with a short backoff |