Code on an instance often needs to call EZGH: a worker that receives from a queue, a job that starts a workflow, a script that uploads to your project. Attach a bot to the instance and that code gets the bot’s access without an API key on the disk. The instance fetches short-lived keys for the bot from its metadata service, and ezgh and the Workflows SDKs do it for you.
The bot’s policies decide what the code can do. A bot can do nothing until policies are attached to it.
Attach a bot
Attaching a bot needs bots.pass on the bot, as well as the usual permission to launch or change the instance. bots.pass lets someone hand the bot’s access to code they run, so grant it as carefully as bots.createApiKey. Removing a bot needs only compute.instances.update.
- To attach at launch, choose a Bot in the launch form. To change it later, open the instance and use Change next to Bot.
- To remove it, select Remove next to Bot and confirm.
ezgh compute instances launch worker-1 --instance-type <type> --image linux/debian:13 \
--ssh-key laptop --bot bot_a1b2c3d4e5f6
ezgh compute instances update worker-1 --bot bot_f6e5d4c3b2a1
ezgh compute instances update worker-1 --no-botGive bot (a bot_… ID) in CreateInstance, or in UpdateInstance with null to remove it. The instance’s bot field shows the bot’s ID and name, or null.
An instance has at most one bot, in its own organization. Changing or removing the bot takes effect for the next key the instance asks for; see Keys.
Example: a queue worker
Say bot_a1b2c3d4e5f6 has a policy allowing queues.messages.receive on the orders queue (acknowledging needs no permission: it uses the receipt handles a receive returns). On an instance launched with that bot, this needs no login, profile or API key. It only names the organization and project:
export EZGH_ORG=acme
export EZGH_PROJECT=shop
while true; do
ezgh queues receive orders --max 10 --wait 20s -o json | ./handle-orders || sleep 5
doneEach ezgh invocation fetches its own fresh key from the instance, and a key request is limited (about 120 a minute per instance, and 2 a second on the instance itself). For a busy queue, don’t run one ezgh per message: receive in batches (--max 10, as above), use ezgh queues receive orders --ack when printing is all the handling there is, or run one long-running process such as a Workflows SDK worker, which fetches a key once and renews it. The || sleep 5 keeps an error from spinning the loop. Acknowledge each message with ezgh queues ack after handle-orders succeeds if you need to. Put the loop in a systemd service and it keeps working for as long as the instance runs, however many keys come and go.
Example: read a secret at boot
To give a server a database password or another value from Secrets without putting it in user data, attach a bot that may read only that secret and fetch the value at boot. See Read a secret on an instance.
How code picks up the credentials
The ezgh CLI and the Workflows SDKs (Go, TypeScript and Python) use the instance’s bot last, only when nothing else is set:
EZGH_API_KEY, or theapiKeyyou pass to an SDK.- The CLI’s active profile (a sign-in or stored key).
- On an EZGH instance, the bot’s key from the metadata service.
So a key you set always wins, and the same code runs unchanged on your laptop (with your profile) and on the instance (with the bot). ezgh auth status and ezgh whoami show the bot (and ezgh whoami the instance) when it’s the one in use. An instance without a bot gets a clear error saying so instead of falling back to anything.
The CLI and SDKs recognize an EZGH instance by its hardware name and ask the metadata service for a key only then, so they don’t slow down anywhere else. They try the metadata service at 169.254.169.254, then at
fd65:7a67:6800::254. On an IPv6-only instance that takes ezgh 0.49.0 or later and Workflows SDK
1.1.1 (TypeScript) or 0.4.1 (Go, Python) or later. The TypeScript SDK reads the hardware name through process.getBuiltinModule, which Node 22.3 or later and Bun have; on older Node pass apiKey.
For other tools, fetch the key yourself; see the metadata service.
Keys
- Each key is valid for 10 minutes. The CLI and SDKs fetch a key when they need one, ask for a new one 5 minutes before it expires, and if an API call answers
401they fetch a new key and retry once. - You never create, store or rotate these keys. They don’t appear in the bot’s API keys list, don’t count against the bot’s key limit, and are removed when they expire.
- Every key is checked on every request like any other key of the bot. Deleting the bot ends its instance keys at once.
- Changing or removing the bot stops new keys for the old bot straight away, but a key already fetched keeps working until it expires, at most 10 minutes later. A stopped instance gets no keys.
- Fetching a key isn’t recorded in Trails. What the key does is: the events show the bot, with the instance as the source of the call.
Who can use the bot’s access
The metadata service asks for a session token before it hands out a key, which stops a web application on the instance from being tricked into fetching it. It doesn’t separate one program on the instance from another.