# Register an agent

Create a one-time code in the app, register the agent against it, and keep it connected.

Registration binds an agent install to your organization and gives it an identity, so the platform can route work to it. From then on the agent authenticates itself with short-lived signed tokens, so there is no long-lived password sitting on the host.

This picks up where [Install the agent](/docs/guides/cli/install/) leaves off, with the binary already on the host. If it is not there yet, install it first. An invite code starts expiring the moment you create it, so it pays to have the host ready before you make one.

![The Agents page with an Invite agent button and a table of five agents showing their status, liveness, version and assigned projects, including one pending registration and one pending approval.](demos/guides/cli-register-an-agent-light.png)
{mode="true" class="guide-image"}

## Create an invite

In the app, open your organization and go to Agents, then create an agent invite. You choose three things:

- **Display name**: how this agent appears in the agents list. Name it after the host or the environment it serves, not after the person who created it.
- **Whether approval is required** before the agent can connect. Leave it on when the person installing the agent is not the person who should authorize it.
- **How long the invite stays valid**: one hour, 24 hours, or seven days. Pick the shortest window that fits how quickly the install will actually happen.

The invite produces a one-time code, and it is shown exactly once. Copy it before you dismiss the panel; afterwards only a hint of it is stored, and an invite you have lost has to be replaced rather than recovered.

## Register on the host

The invite panel in the app shows the exact commands for your system, with the install step first. Run them on the machine where you installed the agent. The register command takes the code from the invite:

```bash
amfelt register --code <one-time-code>
```

These commands use `amfelt`, the executable name.

The agent knows where Amfelt is: unless you tell it otherwise it registers with `https://api.amfelt.com`, and it prints that address before it sends anything. After a successful registration it remembers the address, so `amfelt channel` and the other commands need no endpoint setting.

Two cases need an explicit endpoint: a self-managed or on-premises Amfelt, and a demo or test environment. Pass `--api-url <your-endpoint>` or export `AMFELT_API_ENDPOINT=<your-endpoint>` in the shell you register from. An explicit endpoint always wins over the remembered one and over the default.

The built-in address is only for a first registration. If the agent finds an identity file on the host, in `$AMFELT_DIR`, or in `~/.amfelt`, it refuses to use the default, says so, and does not use your code. Give it the endpoint, or register in a fresh directory with `AMFELT_DIR`. An agent that registered somewhere else never switches to the default.

If the invite requires approval, add `--wait-for-approval` and the command blocks, polling until an administrator approves the agent:

```bash
amfelt register --code <one-time-code> --wait-for-approval
```

Without that flag the command returns as soon as it has registered, and the agent simply waits for approval before it does any work.

Registering into a directory that already holds an identity is refused rather than silently ignored. Pass `--force` only when you mean to replace the identity that is already there.

Registration writes the agent's identity to `$AMFELT_DIR`, or to `~/.amfelt` for the user that runs the command when that is unset. The commands that come after it read the identity from the same place, so run them as the same user with the same `AMFELT_DIR`. [Where the agent keeps its state](/docs/guides/cli/install/#where-the-agent-keeps-its-state) explains the layout.

## Keep it connected

Registration gives the agent an identity. The channel command is what keeps it reachable:

```bash
amfelt channel
```

It connects to the endpoint the agent registered against, which the agent remembered. For a self-managed Amfelt, or when you set an endpoint explicitly at registration, give the same endpoint here with `--api-url` or `AMFELT_API_ENDPOINT`. When a service manager starts it, set `AMFELT_DIR` in the service's environment if you use it, and the endpoint if you set one explicitly, not only in your own shell.

This opens the long-lived outbound connection the platform dispatches runs over, and heartbeats so the agents list shows the agent as connected. On Linux, `install.sh --service` writes the systemd unit for you ([Install the agent](/docs/guides/cli/install/#run-it-as-a-service-on-linux)). Run it under whatever supervises services on that host (systemd, launchd, a Windows service) so it comes back with the machine. It reconnects on its own with backoff when the connection drops.

## Assign it to a project

An agent belongs to the organization, but it does its work for a project. Assign it to the projects whose sources and data platform it should connect to, otherwise discovery and jobs have nothing to run on.

## Next

Confirm the install is sound: [Check agent health](/docs/guides/cli/check-agent-health/).