---
title: "Install the agent"
description: "Create a node bot, then install the agent on an EZGH instance or any other Linux machine so it registers as a node."
---

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

# Install the agent

The agent runs as root under systemd, connects out to EZGH and registers the machine as a node
in a project. It acts as a [bot](/iam/bots), the **node bot**: the bot's key is all it needs to
register.

## Create a node bot

A node bot needs only two actions: `fleets.nodes.register` on the project and
`fleets.nodes.connect` on its nodes. The managed policy `FleetsManagedNodeAccess` has both.

> **Caution**
>
> **Anyone with a shell on a node can act as its node bot.** On an EZGH instance, any process,
> even one running as `ezgh-user`, can fetch the instance bot's key from the metadata service. Give
> a node bot `FleetsManagedNodeAccess` and nothing else, and don't reuse it for anything else,
> least of all `fleets.*` actions on other nodes. The console says so on each node's page and when
> you connect.

Use one node bot per group of machines (web servers, build machines), so that revoking one group
doesn't touch the others.

### Console

1. Open **Fleets** > **Nodes** and choose **Set up a node Bot**.
2. Name the bot and create it. The console attaches `FleetsManagedNodeAccess` to it and shows the
install commands for it.
### CLI

```sh
ezgh iam bots create web-nodes
ezgh iam policies attach FleetsManagedNodeAccess --bot web-nodes
```

`FleetsManagedNodeAccess` lets the bot register machines in any project of the organization. To
keep it to one project, give the bot a policy of your own instead:

```json
{
  "statements": [
    {
      "effect": "allow",
      "actions": ["organizations.get", "fleets.nodes.register", "fleets.nodes.connect"],
      "resources": [
        "ezgh:*:org_k3f9a0x2m7qp",
        "ezgh:*:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2",
        "ezgh:*:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2:nod_*"
      ]
    }
  ]
}
```

## Project and organization IDs

The agent names the project, and the organization where it's needed, by its **ID**: a UUID such
as `9f3c2a1e-6b7d-4e8f-a0b1-c2d3e4f5a6b7`, not its `prj_…` or `org_…` name. The console's install
commands fill it in, and `ezgh projects get` and `ezgh orgs get` show it.

## On an EZGH instance

The agent gets short-lived keys for the instance's [bot](/compute/instance-bots) from the
metadata service, so there's no key to store.

1. Attach the node bot to the instance (the instance's **Bot**, or
   `ezgh compute instances update web-1 --bot bot_a1b2c3d4e5f6`).
2. On the instance, run:

   ```sh
   curl -fsSL https://get.ezghcloud.com/fleets/install.sh | sudo sh -s -- --project 9f3c2a1e-6b7d-4e8f-a0b1-c2d3e4f5a6b7
   ```

The node is linked to the instance and named after it, and it has the instance's tags, kept up to
date each time the agent connects. If the instance has no bot yet, the agent waits and checks
again every few minutes, so attaching the bot later is enough.

## On another Linux machine

### API key

1. Create an [API key](/iam/bots#create-an-api-key-for-a-bot) for the node bot, and save it on
the machine as `node-bot.key` (`chmod 600 node-bot.key`).
2. Run:

```sh
curl -fsSL https://get.ezghcloud.com/fleets/install.sh | sudo sh -s -- \
  --project 9f3c2a1e-6b7d-4e8f-a0b1-c2d3e4f5a6b7 --api-key-file node-bot.key
```

The script copies the key to `/etc/ezgh-fleets-agent/credentials`, readable only by root.
3. Delete `node-bot.key`.
### OIDC

Where the machine has a workload identity, such as a Kubernetes service account token, the
agent exchanges it for short-lived keys instead, and no key is stored. Set up the bot's
[OIDC trust](/iam/kubernetes) first, then run:

```sh
curl -fsSL https://get.ezghcloud.com/fleets/install.sh | sudo sh -s -- \
  --project 9f3c2a1e-6b7d-4e8f-a0b1-c2d3e4f5a6b7 --organization 4d5e6f70-8192-4a3b-9c4d-5e6f708192a3 \
  --oidc-bot bot_a1b2c3d4e5f6 --oidc-token-file /var/run/secrets/ezgh/token
```

A node outside EZGH has no tags until you add them: in the console on the node's page, or in
[UpdateNode](/fleets-api/UpdateNode/). The agent never sets a node's tags, so a machine
can't tag itself into a run.

## What the install script does

The script adds the signed EZGH package repository for apt or yum, installs the
`ezgh-fleets-agent` package, writes `/etc/ezgh-fleets-agent/config.yaml` and starts the service.
It does nothing the package can't do, and it's short enough to read before you run it. You can
also add the repository and install the package yourself: `.deb`, `.rpm` and a static tarball are
published for amd64 and arm64. The agent updates with the rest of the machine's packages.

```yaml
# /etc/ezgh-fleets-agent/config.yaml
project: 9f3c2a1e-6b7d-4e8f-a0b1-c2d3e4f5a6b7      # required: the project's ID
organization: 4d5e6f70-8192-4a3b-9c4d-5e6f708192a3 # optional: learned from the bot's key
credentials:
  source: auto   # auto | metadata | file | oidc
  file: /etc/ezgh-fleets-agent/credentials
  oidc: { bot: bot_a1b2c3d4e5f6, tokenFile: /var/run/secrets/ezgh/token }
```

`auto` uses the metadata service on an EZGH instance, and the key file elsewhere.

## The node's binding

When the agent first registers, it makes a key pair of its own and keeps the private half in
`/var/lib/ezgh-fleets-agent`, readable only by root. It signs every connection with it. So a copied
bot key can register a new node, but it can't take over an existing one.

- **An instance has one node.** Registering again from an instance that already has one fails.
  If you reinstall the agent or rebuild the disk, choose **Reset** on the node's page (or
  `ezgh fleets nodes reset web-1`). Reset ends the node's sessions and shows it as
  **Awaiting registration**, and the next registration from the instance keeps the node's ID.
  Check the agent version and the time it registered afterwards.
- **Another machine** registers a new node each time its state directory is lost. Deregister the
  old one. Resetting a node on another machine works the same way: its agent registers again as
  a new node, with a new ID and no tags, and the reset node stays **Awaiting registration** until
  you deregister it.

## Disconnect a machine

Removing the bot's permission, deleting the bot or revoking its key disconnects its nodes within
10 minutes. To remove a node, choose **Deregister** on its page or run
`ezgh fleets nodes deregister web-1`, then uninstall the package from the machine.

## Limits

A project can have 1,000 nodes, online or not (adjustable in [Service quotas](/quotas)).

Source: https://docs.ezghcloud.com/fleets/install-the-agent/index.mdx
