Code in a sandbox that calls EZGH (sends to a queue, reads a secret, starts another sandbox) needs a credential. Create the sandbox with a bot and that code gets the bot’s access with no API key in the image or in an environment variable. Code in the sandbox fetches short-lived keys for the bot from an address inside it.
The bot’s policies decide what the code can do, and they are the only limit. A bot can do nothing until policies are attached to it.
Create a sandbox with a bot
It needs bots.pass on the bot, as well as sandboxes.sandboxes.create. bots.pass lets someone hand the bot’s access to code they run, so grant it as carefully as bots.createApiKey.
- Open Sandboxes and select Create sandbox.
- Choose a Bot, fill in the rest of the form and select Create sandbox.
The sandbox’s page shows its bot under Configuration.
Give bot (a bot_… ID) in CreateSandbox. The sandbox’s bot field shows the bot’s ID and name, or null. In a list, name is null.
ezgh sandboxes create "$IMAGE" --name worker --bot bot_a1b2c3d4e5f6
ezgh sandboxes get workerezgh sandboxes get shows the bot on its Bot line.
| Error | When |
|---|---|
400 invalid_request at bot |
The organization has no such bot |
403 access_denied naming bots.pass |
You may not pass this bot |
Running commands in a sandbox that has a bot, attaching to one, and writing its files also need bots.pass on its bot, as well as sandboxes.sandboxes.exec or sandboxes.sandboxes.writeFile. Reading files needs only sandboxes.sandboxes.readFile.
A sandbox has at most one bot, in its own organization. The bot is set when the sandbox is created and can’t be changed or removed afterwards: to use another bot, create another sandbox. To cut a sandbox’s access, detach the bot’s policies or delete the bot.
Use ezgh in the sandbox
ezgh 0.65.0 or later needs no login and no API key in a sandbox that has a bot: it fetches the bot’s keys itself and renews them (a new key 5 minutes before one expires, and once more if an API call answers 401). EZGH_API_KEY and a profile’s stored credential take precedence when set.
ezgh auth statusProfile: default (built-in default)
Domain: ezghcloud.com
Credential: sandbox credentials for bot bot_a1b2c3d4e5f6ezgh whoami shows the bot as the principal and the sandbox on a Sandbox line; it needs organizations.get in the bot’s policies. Name the project with --project or EZGH_PROJECT:
export EZGH_PROJECT=shop
ezgh queues send results --body "$(cat /tmp/result.json)"Fetch a key
The sandbox answers at http://169.254.169.254 and http://[fd65:7a67:6800::254], the same requests an instance answers. Only code inside the sandbox can reach these addresses. First get a session token, with how long it should last in seconds (1 to 21600), then use it to fetch the credentials:
TOKEN=$(curl -s -X PUT -H "EZGH-Metadata: true" \
-H "EZGH-Metadata-Token-TTL-Seconds: 21600" \
http://169.254.169.254/ezgh/v1/token)
EZGH_API_KEY=$(curl -s -H "EZGH-Metadata: true" -H "EZGH-Metadata-Token: $TOKEN" \
http://169.254.169.254/ezgh/v1/credentials | jq -r .apiKey)
curl -s -H "Authorization: Bearer $EZGH_API_KEY" \
"https://sandboxes.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/sandboxes"Keep the key in a variable or in memory. Don’t print it or write it to a file or a log. The credentials request answers:
{
"apiKey": "ezgh_…",
"expiresAt": "2026-11-12T18:30:00Z",
"bot": "bot_a1b2c3d4e5f6"
}| Request | Returns |
|---|---|
PUT /ezgh/v1/token |
A session token. Headers: EZGH-Metadata: true and EZGH-Metadata-Token-TTL-Seconds |
GET /ezgh/v1/credentials |
The bot’s temporary API key. Headers: EZGH-Metadata: true and EZGH-Metadata-Token |
Use apiKey as a bearer token (Authorization: Bearer ezgh_…) until expiresAt, which is 10 minutes after the request. Fetch a new key about 5 minutes before that, and once more if an API call answers 401. Every request to /ezgh/v1/credentials returns a new key; don’t call it per API request.
| Error | When |
|---|---|
400 metadata_header_required |
The EZGH-Metadata: true header is missing |
403 forwarded_request |
The request carries X-Forwarded-For or another header a proxy adds |
400 invalid_ttl |
EZGH-Metadata-Token-TTL-Seconds is missing, isn’t a plain whole number, or is outside 1 to 21600 |
401 invalid_token |
The token is missing, expired or unknown; get a new one |
404 no_bot |
The sandbox has no bot, or the bot no longer exists |
429 rate_limited |
Too many requests; wait for Retry-After and keep using the current key |
503 unavailable |
The key can’t be issued right now; retry after Retry-After, and keep using the current key until it expires |
A sandbox can fetch 120 keys a minute. Inside the sandbox, credentials requests are limited to 2 a second, with bursts of 10.
Keys
- Each key is valid for 10 minutes.
- You never create, store or rotate these keys. They don’t appear in the bot’s API keys list and don’t count against the bot’s key limit.
- Every key is checked on every request like any other key of the bot. Deleting the bot ends its sandbox keys at once; the sandbox then shows the bot by its ID alone, and key requests answer
404 no_bot. - Fetching a key doesn’t count as activity for idle suspend.
- Fetching a key isn’t recorded in Trails. Creating the sandbox is, with its bot. What a key does is recorded as the bot, with the sandbox as the source of the call.
| When the sandbox is | Keys |
|---|---|
| Suspended or stopped | None are issued. A key fetched before stops working within 10 minutes |
| Resumed or started again | Issued again, for the same bot |
| Deleted | None are issued. A key fetched before stops working within 10 minutes |
The session token asked for before a key stops a web application in the sandbox from being tricked into fetching it. It doesn’t separate one program in the sandbox from another.