---
title: "Give an instance access to EZGH"
description: "Attach a bot to an instance so code on it can call EZGH APIs, with short-lived keys it fetches itself and nothing to configure or store."
---

> 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 an instance access to EZGH

Code on an instance often needs to call EZGH: a worker that receives from a [queue](/queues), a job that starts a [workflow](/workflows), a script that uploads to your project. Attach a [bot](/iam/bots) 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](/compute/user-data-and-metadata#instance-bot-credentials), 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`](/iam/bots#create-an-api-key-for-a-bot). Removing a bot needs only `compute.instances.update`.

### Console

1. To attach at launch, choose a **Bot** in the launch form. To change it later, open the instance and use **Change** next to **Bot**.
2. To remove it, select **Remove** next to **Bot** and confirm.
### CLI

```sh
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-bot
```
### API

Give `bot` (a `bot_…` ID) in [CreateInstance](/compute-api/CreateInstance/), or in [UpdateInstance](/compute-api/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](#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:

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

Each `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](/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](/secrets/instances).

## 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:

1. `EZGH_API_KEY`, or the `apiKey` you pass to an SDK.
2. The CLI's active profile (a sign-in or stored key).
3. 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](/compute/user-data-and-metadata#instance-bot-credentials).

## 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 `401` they 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](/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

> **Caution**
>
> Everything running on the instance can fetch the bot's keys, **including containers**: a container reaches the metadata service through the instance's address. A compromised container, or any code on the instance that you don't trust, is a compromised bot. Give the bot only the policies the code on that instance needs, and keep untrusted workloads on instances without a bot.

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.

Source: https://docs.ezghcloud.com/compute/instance-bots/index.mdx
