---
title: "Give a sandbox a Bot"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Give a sandbox a Bot

Code in a sandbox that calls EZGH (sends to a [queue](/queues), reads a [secret](/secrets), starts another sandbox) needs a credential. Create the sandbox with a [bot](/iam/bots) 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.

> **Caution**
>
> **Any code in the sandbox can use the bot.** Every program running in it, including code you didn't write, can fetch the bot's keys and call EZGH as the bot. Give a sandbox's bot only the policies that code may use. Never give a sandbox a bot that has `bots.pass` or any action that changes IAM (creating API keys, attaching policies, changing groups, users or bots): code holding such a bot could give itself more access.

The bot's [policies](/iam/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`](/iam/bots#create-an-api-key-for-a-bot).

### Console

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**.
### API

Give `bot` (a `bot_…` ID) in [CreateSandbox](/sandboxes-api/CreateSandbox/). The sandbox's `bot` field shows the bot's ID and name, or `null`. In a list, `name` is `null`.
### CLI

```sh
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.

```sh
ezgh auth status
```

```text
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`:

```sh
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](/compute/user-data-and-metadata#instance-bot-credentials) 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:

```sh
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:

```json
{
  "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](/sandboxes/lifecycle).
- Fetching a key isn't recorded in [Trails](/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.

Source: https://docs.ezghcloud.com/sandboxes/bots/index.mdx
