Connect an agent and send your first message

By the end of this tutorial you’ll have a live agent connected to Alfe from your own machine, verified from both the CLI and the Agent API, and you’ll have sent it a message. It takes a few minutes.

Before you start

• Node.js (a current LTS) and npm.
• An Alfe account — sign up at app.alfe.ai. (Agents can also self-onboard over MCP; see Agent-led bootstrap.)

1. Install the CLI

npm

npm i @alfe.ai/cli -- -g

pnpm

pnpm add @alfe.ai/cli -g

bun

bun add @alfe.ai/cli -g

Then confirm it’s on your PATH:

Terminal

alfe --version

2. Authenticate

Link the CLI to your account. By default this opens your browser to authorize the device:

alfe login

On a headless machine, pass a pre-issued key instead (or set ALFE_API_KEY):

alfe login --token <your-api-key>

Confirm who you are:

alfe whoami

3. Connect the agent

alfe setup connects an agent on this machine. It installs and configures the agent runtime, starts the local gateway daemon, and registers the Alfe platform tools so the agent can reach memory, model routing, and integrations:

alfe setup

When it finishes, the daemon is running and the agent is connected. Check its health any time:

alfe doctor

On a server?

For unattended, cloud-init-style provisioning, use alfe setup --managed, which reads everything from environment variables instead of prompting.

4. Confirm over the Agent API

Your connected agent has its own API key (written into ~/.alfe/config.toml by setup, and the value of ALFE_API_KEY if you set it). Ask the API who it is:

Note

The command below reads $ALFE_API_KEY from your shell. If you didn’t set it during login, export it first — or copy the key from ~/.alfe/config.toml.

Terminal

curl https://api.alfe.ai/agent/identity/whoami \
  -H "Authorization: Bearer $ALFE_API_KEY"

{ "data": { "agentId": "agt_…", "tenantId": "…" } }

Seeing your agentId confirms the agent is authenticated and reachable. See Authentication for the full token model.

5. Say hello

Open your agent in the dashboard at app.alfe.ai and send it a message. To talk to it where you already work, connect a channel like Slack or Discord from Integrations — each agent gets its own bot identity on the channel.

Next steps

• Give your agent memory — store and recall facts over the API.
• Receive a webhook — have your agent react to external events.
• Explore the full Agent API reference.