DE Start free

Docs

Quickstart

From sign-up to your first VM sandbox. Start with the open source eai CLI, or call the REST API directly. The API base URL is https://hive-api.hive.eai.onl.

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:

install
curl -fsSL https://raw.githubusercontent.com/cierrateam/eai-cli/main/install.sh | sh

Or with Homebrew:

Homebrew
brew install cierrateam/tap/eai

Create an account and log in. The free tier needs no credit card.

account
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.

run
eai hive run python:3.12-slim -- python -c "print(6*7)"

List your sandboxes and delete one by its ID:

list and delete
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.

Get Pro See pricing

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.

Open the sign-up page

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:

shell
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").

POST /sandbox
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:

response (example, shortened)
{
  "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:

shell
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:

GET /sandbox/{id}
curl -s "$API/sandbox/$SANDBOX_ID" \
  -H "Authorization: Bearer $HIVE_API_KEY"
FieldMeaning
statusHigh-level state, for example pending, running, succeeded or failed
readytrue once the container is up. Useful for services that expose a port
exit_codeExit code of your command once it has finished (0 means success)
expires_atWhen 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:

GET /sandbox/{id}/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:

POST /sandbox/{id}/extend
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:

DELETE /sandbox/{id}
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.

FieldTypeDescription
imagestringAny OCI image, for example python:3.12-slim or your own Docker image
commandlist of stringsCommand to run instead of the image default
restartstring"never" for one-off jobs that run until they exit, "always" for services that should stay up
ttlintegerLifetime in seconds. On the free tier at most 3600 (1 hour)
cpu_milliintegerCPU in millicores. 1000 is one vCPU
memory_miintegerMemory in MiB
portintegerPort of your service inside the sandbox. It is exposed under the sandbox URL https://<id>.hive.eai.onl
envobjectEnvironment variables as key and value strings
internetstring"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.

POST /sandbox · service with a port
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

LimitFree tier
Sandbox hours20 hours per month
Concurrent sandboxesUp to 2
CPU per sandboxUp to 2 vCPU (cpu_milli ≤ 2000)
Memory per sandboxUp to 2 GB RAM (memory_mi ≤ 2048)
Runtime per sandboxUp to 1 hour per run
Outbound e-mailPorts 25, 465 and 587 are blocked to prevent abuse
Credit cardNot 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.

Talk to us about Pro

Error codes

Errors are returned as JSON with a detail message that says what went wrong.

HTTP statusMeaningWhat to do
401Invalid or missing API keyCheck the Authorization header and the key
402Free plan limit: monthly hours used up, or more CPU, memory or runtime requested than the plan allowsLower the request, wait for the next month, or ask us about paid plans
403Account suspendedContact info@cierra.ai
422Validation error in the request bodyFix the request body. The message names the field
429Too many concurrent sandboxesDelete a running sandbox or wait until one expires
503no_capacity: no free capacity right nowTry again shortly, ideally with a short backoff
The complete, always current API description lives in the OpenAPI reference.