HTTP API

Create. Execute.
Stay in control.

Create your Sandbox account with your email address, or sign in if you already have one. No existing AGNT account or app subscription is required. Headless agents can register and fund themselves over HTTP.

Open your account →

Delegate work, not account control

Owner-only task grants issue an expiring Small-job credential with lifetime authorization limits. The key cannot change billing or enlarge its grant. Authorized maximum cash and compute-minutes accumulate even when a job finishes early; billing is still settled independently.

POST /sandbox/v1/grants
{"expiresAt":1790000000000,"budgetMicroUSD":1000000,"maxJobMicroUSD":120000,"maxUnits":20,"maxOutstanding":1}

Use the returned task_ key for /jobs/quote, /jobs, /jobs/ID and /jobs/ID/artifacts/ARTIFACT_ID. Owner GET/DELETE /grants lists or revokes grants. Revoking a key blocks new requests but does not cancel already authorized jobs.

JavaScript job helper · Python job helper

Readiness and results

/health reports process liveness. /readiness reports fresh authenticated idle-worker polling and current fleet occupancy. Signed approval is separately enforced on each launch. A busy or absent worker rejects new admission rather than reserving money into an unusable queue.

/artifacts lists recent result files, sizes, producer job and expiry. Download important outputs before expiry. Daily encrypted off-server backups support disaster recovery; backup retention is separate from user-download expiry and is not indefinite preservation.

Optional checks validate required output existence, SHA-256 or required JSON keys outside the guest. Receipts distinguish executionStatus, artifactStatus, cleanupStatus and checksStatus. Exit zero alone does not establish correctness.

Run a bounded job

Quote first, then authorize the maximum cash debit. Jobs upload inputs, run a command, export selected outputs, and destroy the VM. Completion is reported only after teardown.

POST /sandbox/v1/jobs/quote
{"command":"echo hello > result.txt","outputs":["result.txt"],"lifetimeSeconds":120}

POST /sandbox/v1/jobs   + Idempotency-Key
{"command":"echo hello > result.txt","outputs":["result.txt"],"lifetimeSeconds":120,"maxChargeMicroUSD":120000}

GET /sandbox/v1/jobs/JOB_ID
DELETE /sandbox/v1/jobs/JOB_ID

Inputs: up to eight {path,base64} objects, at most 8 MB combined; input paths must be unique root filenames. Outputs: up to eight relative file paths. Commands can create subdirectories. Download result.artifacts through GET /artifacts/ID. States: queued, uploading, executing, exporting, stopping, completed/failed/cancelled. Resume polling the same job after a disconnect—do not resubmit it with a new key.

Quote is advisory, not a reservation; execution rechecks prices and balance atomically. maxChargeMicroUSD is mandatory for paid usage (1 dollar = 1,000,000 microUSD); zero permits included-only work. Time is bounded from admission, including queue/boot, but only ready runtime is billed. Choose a deadline long enough for file transfer and export. Default 120 seconds, maximum 900.

Prepaid balances fund pay-as-you-go execution without a subscription. Optional monthly plans include compute-minutes and a lower rate beyond them. There are no automatic card charges. Platform failures refund unused reservations; confirmed lost-worker failures on managed jobs release their runtime authorization. Customer-code failures and timeouts consume runtime. Queue expiry or failed provisioning costs nothing.

Headless signup (agents)

No email, no browser. The secret is your identity. Store it securely; it is shown only once.

# Headless signup. Store the secret: it is shown only once.
curl -X POST https://sandbox.agnt.gg/sandbox/v1/agents \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent"}'

# 201 { "agentId": "agt_...", "secret": "sandbox_...", "balance": 0,
#       "fund": { "claimUrl": "https://sandbox.agnt.gg/claim/agt_..." } }
# Share claimUrl with the person funding the agent, or pay with x402.
# Fund the account; prepaid jobs do not require a hosting plan.

No subscription is needed for prepaid execution. Fund the account, then submit a job with a spending cap. Inspect GET /sandbox/v1/usage and /plans for the applicable allowance and rate.

Agents pay for themselves with x402

Request a funding order, sign the returned authorization in USDC on Base, and the payment credits this product’s prepaid balance. Settlement uses the Coinbase facilitator and is recorded as a Stripe payment. Your wallet needs USDC on Base; the facilitator pays gas.

The client (JavaScript)

// npm i @x402/core @x402/evm viem
import { privateKeyToAccount } from 'viem/accounts';
import { x402Client } from '@x402/core/client';
import { registerExactEvmScheme } from '@x402/evm/exact/client';

const base = 'https://sandbox.agnt.gg/sandbox/v1';
const auth = { Authorization: 'Bearer ' + process.env.SANDBOX_SECRET,
  'Content-Type': 'application/json' };
const client = new x402Client().setSpendControls({ maxAmountPerPayment: '$10' });
registerExactEvmScheme(client, {
  signer: privateKeyToAccount(process.env.WALLET_PRIVATE_KEY),
  networks: ['eip155:8453']
});
const created = await fetch(base + '/funding/x402', {
  method: 'POST', headers: auth, body: JSON.stringify({ amountCents: 1000 })
});
if (created.status !== 402) throw new Error('Funding order rejected');
const order = await created.json();
const payload = await client.createPaymentPayload(order.requirements);
const paid = await fetch(base + '/funding/x402/' + order.orderId, {
  method: 'POST', headers: { ...auth,
    'PAYMENT-SIGNATURE': Buffer.from(JSON.stringify(payload)).toString('base64') },
  body: '{}'
});
if (!paid.ok) throw new Error('Payment rejected: ' + await paid.text());
const result = await paid.json();
if (result.state !== 'credited') throw new Error('Poll order until credited');
// Balance is ready for pay-as-you-go jobs; no hosting purchase needed.
// Quote a job, then POST /jobs with maxChargeMicroUSD.

Payment limits

Top-ups: $10, $25, or $50. Set an explicit client spending cap at least as large as the selected payment.
Orders expire after 10 minutes. Poll the same order on uncertain responses; do not submit a new payment blindly.
Protocol x402 v2, network eip155:8453, asset USDC. Never send a wallet private key to the API.

Create your Sandbox account

Verify your email, or register a headless agent.
Add prepaid credit ($10 minimum) through Stripe or x402.
Submit a bounded job. A monthly plan is optional.
Download the results after automatic teardown.

The account page also accepts a Sandbox API secret. Human card checkout requires an email-authenticated account. Agents can use x402 or share their funding link.

Create and execute

All API calls except signup and public policy require Authorization: Bearer <secret>. Creation and execution requests require Idempotency-Key. Reuse the same key on retries.

curl -X POST https://sandbox.agnt.gg/sandbox/v1/sandboxes \
  -H 'Authorization: Bearer sandbox_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: create-your-unique-id' \
  -d '{"size":"small","lifetimeSeconds":600,"network":"offline"}'

# 202 { "id": "...", "state": "queued", ... }
# Poll GET /sandbox/v1/sandboxes/ID until state is "ready".
# Queued/provisioning time is not billed; ready time is billed even while idle.

curl -X POST https://sandbox.agnt.gg/sandbox/v1/sandboxes/ID/executions \
  -H 'Authorization: Bearer sandbox_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: execute-your-unique-id' \
  -d '{"command":"python3 --version && node --version","timeoutSeconds":60}'

# 202 { "id": "...", "state": "queued" }
# Poll GET /sandbox/v1/executions/EXECUTION_ID for exit_code and output.
# output is a JSON-encoded object. Parse it to read stdout and truncation flags.
# A command timeout terminates the sandbox, not just the command.

Lifecycle: queued → provisioning → ready → stopping → destroyed. Failed provisioning is not billed. A lost worker retains reservations until teardown is confirmed. Commands are not replayed automatically after a worker failure.

Execution results include state, exit_code, and output. Parse the JSON-encoded output object to read its output, truncated, and timedOut fields.

Files and retained artifacts

# Upload a new file (8 MB maximum; existing files are never overwritten).
curl -X POST https://sandbox.agnt.gg/sandbox/v1/sandboxes/ID/uploads \
  -H 'Authorization: Bearer sandbox_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: upload-your-unique-id' \
  -d '{"path":"input.txt","base64":"aGVsbG8="}'

# Export: POST /sandbox/v1/sandboxes/ID/exports {"path":"result.txt"}
# Both return { id, state: "queued" }; poll GET /sandbox/v1/transfers/ID.
# A completed export returns result.artifactId.
# GET /sandbox/v1/artifacts/ARTIFACT_ID downloads its bytes (authenticated).

Paths are relative to /workspace. Parent directories must exist. Uploads never overwrite an existing file. Traversal, symlinks, hardlinks, and special files are rejected. Poll transfers until completed or failed before using their results.

Exported artifacts remain available for 1, 7, or 30 days, within the plan’s storage cap. Downloads require authentication and consume the pooled monthly transfer allowance (1, 5, or 15 GB). Downloaded active content remains untrusted.

Receivers and signed delivery

curl -X POST https://sandbox.agnt.gg/sandbox/v1/webhooks \
  -H 'Authorization: Bearer sandbox_...' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-agent.example/events"}'

# 201 { "id": "...", "secret": "..." } — save the signing secret.
# HMAC-SHA256(secret, timestamp + "." + rawBody)
# Headers: X-AGNT-Event-ID, X-AGNT-Timestamp, X-AGNT-Signature: v1=<hex>
# Verify signature and timestamp freshness; deduplicate on event ID.
# GET /sandbox/v1/notifications and /webhook-deliveries show delivery history.

Lifecycle messages contain {id, type, objectId, state, createdAt}. Examples include sandbox.ready, sandbox.destroyed, execution.completed, and artifact.retained.

Verify HMAC-SHA256 over the timestamp, a period, and the exact raw body. Reject stale timestamps and deduplicate on event ID. Receivers must use public HTTPS on port 443; private networks and redirects are rejected. Failed deliveries retry with backoff. Repeated failures pause a receiver; remove and register it again after correcting the destination.

Keys, cancellation, and teardown

POST /sandbox/v1/keys
{"scopes":["sandbox:read","sandbox:execute"],"sandboxId":"SANDBOX_ID"}

GET    /sandbox/v1/keys
DELETE /sandbox/v1/keys/KEY_ID

# Account-level operations require sandbox:manage.
# Resource-bound keys cannot manage funding or create more environments.

curl -X DELETE https://sandbox.agnt.gg/sandbox/v1/sandboxes/ID \
  -H 'Authorization: Bearer sandbox_...'

# Poll GET /sandbox/v1/sandboxes/ID until state is "destroyed".
# Guest execution stops, scratch storage is removed, unused reservations release.
# Explicitly exported artifacts survive until their retention window ends.

Revoked keys stop authenticating immediately. Destroying a session is irreversible. Its temporary filesystem disappears; only exported artifacts remain until expiry.

Pricing, limits, and protected terms

Execution plans

Start with $10 prepaid credit. No subscription required: 6¢ per compute-minute. Regular users can choose a monthly plan.

Plan	Monthly price	Included compute-minutes	Roughly	Extra minutes	Job deadline	Artifacts
Starter	$5	100	50 default jobs	4¢/min	15 minutes	250 MB · 1 day
Pro	$15	400	200 default jobs	3¢/min	15 minutes	1 GB · 7 days
Business	$39	1,200	600 default jobs	2.5¢/min	15 minutes	3 GB · 30 days

A compute-minute is one minute of a Small sandbox (1 vCPU, 1 GB RAM). Pay as you go: Small 6¢/min, Medium 12¢/min, Large 24¢/min. Every run rounds up to a whole minute, and a default job runs 2 minutes. Queue and provisioning time are not billed. Included minutes reset on day 1 UTC and do not roll over; purchased credit persists. Shared worker capacity is not reserved concurrency. AI inference is not included.

Default deadline 120 seconds; new jobs and sessions have a 15-minute maximum. Existing paid or transition entitlements remain visible in /usage. A Small sandbox (1 vCPU, 1 GB) uses one compute-minute per minute; Medium (2/2) uses two and Large (4/4) uses four and requires Pro or Business. Scratch is memory-backed. Offline networking only. No snapshots, custom images, or dedicated concurrency promises.

GET /sandbox/v1/usage
GET /sandbox/v1/plans
POST /sandbox/v1/hosting/purchase {"plan":"starter"}
PUT /sandbox/v1/hosting/preferences {"autoRenew":false,"allowOverage":false}

Execution plans

Start with $10 prepaid credit. No subscription required: 6¢ per compute-minute. Regular users can choose a monthly plan.

Plan	Monthly price	Included compute-minutes	Roughly	Extra minutes	Job deadline	Artifacts
Starter	$5	100	50 default jobs	4¢/min	15 minutes	250 MB · 1 day
Pro	$15	400	200 default jobs	3¢/min	15 minutes	1 GB · 7 days
Business	$39	1,200	600 default jobs	2.5¢/min	15 minutes	3 GB · 30 days

Already subscribe to AGNT?

Paid AGNT includes a monthly execution allowance: Personal 100 compute-minutes, Always-On 300, Business and Enterprise 600. Standalone and bundled allowances do not stack; the higher applicable allowance applies. Existing paid periods and transition allowances retain their terms until the date shown in your account. Any paid execution requires an explicit per-run spending cap.

Create. Execute.Stay in control.

Delegate work, not account control

Readiness and results

Run a bounded job

Headless signup (agents)

Agents pay for themselves with x402

The client (JavaScript)

Payment limits

Create your Sandbox account

Create and execute

Files and retained artifacts

Receivers and signed delivery

Keys, cancellation, and teardown

Pricing, limits, and protected terms

Execution plans

Execution plans

Create. Execute.
Stay in control.