Skip to content

Give a sandbox a Bot

Create a sandbox with a bot so code in it can call EZGH APIs with short-lived keys it fetches itself, instead of an API key in its environment.

Updated View as Markdown

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.

  1. Open Sandboxes and select Create sandbox.
  2. 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 worker

ezgh 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 status
Profile:     default (built-in default)
Domain:      ezghcloud.com
Credential:  sandbox credentials for bot bot_a1b2c3d4e5f6

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

Navigation

Type to search…

↑↓ navigate↵ selectEsc close