# Set Up an Agent

This guide walks you through creating an agent that runs as a Telegram bot powered by Claude - entirely from the `dvx` CLI. By the end you'll have a bot you can message on Telegram that replies using Claude with full conversation history.

## Prerequisites

- The **`dvx` CLI** installed and signed in - see the [Quickstart](/quickstart/).
- An **LLM API key** (e.g. an Anthropic key starting with `sk-ant-`).
- A **Telegram bot token** from [@BotFather](https://t.me/BotFather).
- The **Telegram user IDs** of everyone who should be allowed to talk to the bot.

You do **not** need to run any infrastructure - Daevix operates the control plane, the enclave, and the LLM proxy for you.

## Step 1: Get your Telegram bot token

1. Open Telegram and message [@BotFather](https://t.me/BotFather).
2. Send `/newbot` and follow the prompts to name your bot.
3. BotFather gives you a token like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`.
4. Save it for Step 4.

## Step 2: Get your Telegram user IDs

Each person who may talk to the bot needs their numeric Telegram user ID:

1. Message [@userinfobot](https://t.me/userinfobot) on Telegram.
2. It replies with the user ID (a number like `123456789`).
3. Collect the IDs of everyone who should have access.

## Step 3: Set your LLM API key

The agent calls Claude through the Daevix LLM proxy, which injects your credential so the agent never sees it. Set the key once at the organization level (shared by all agents):

```bash
dvx secret set llmproxy:llm.api_key --value sk-ant-...
```

To use a different key for just this agent, override it per agent:

```bash
dvx agent secret set my-assistant llmproxy.api_key --override-service llmproxy --value sk-ant-...
```

The proxy checks the agent-level override first and falls back to the org-level key.

## Step 4: Create the agent

Create the agent on one of the enclaves available to you (the enclave is the `broker` component in the CLI):

```bash
dvx broker list
dvx agent create my-assistant --broker-id <id>
```

The agent starts in `created` status. Connect Telegram before it goes live.

## Step 5: Connect Telegram

Linking a Telegram channel validates the bot token, stores it as a secret, and records who's allowed to message the bot - in one command:

```bash
dvx agent channel telegram link my-assistant \
  --bot-token '123456:ABC-DEF...' \
  --allowed-users 123456789,987654321
```

Messages from any user ID not in `--allowed-users` are silently ignored. (Omit `--bot-token` to be prompted for it via stdin instead of putting it in your shell history.)

## Step 6: Provisioning and bootstrap

With the agent created and its secrets in place, the enclave provisions and bootstraps it automatically - no manual steps:

1. The enclave provisions a host for the agent and injects a single-use bootstrap token.
2. The agent exchanges the token for its **identity bundle** - a platform JWT, a refresh token, and its secrets.
3. The agent points Claude Code at the LLM proxy and starts the Telegram bot.
4. It begins a JWT refresh loop to keep its short-lived identity current.

When the agent calls Claude, the request flows through the proxy, which validates the agent's JWT, injects your real LLM key, forwards the request, and logs it for audit - the agent never sees the key.

Watch it come up:

```bash
dvx agent get my-assistant     # status: created → provisioning → active
dvx agent logs my-assistant    # stream the agent's output
```

## Step 7: Talk to your bot

Open Telegram, find your bot by the name you gave it in BotFather, and send a message. The bot:

1. Receives the message.
2. Checks that your user ID is in the allowed list.
3. Sends the message to Claude with conversation history.
4. Replies with Claude's response.

Conversations are persistent per user - the agent resumes the same Claude session across messages.

## Troubleshooting

### Agent stays in `created` status

- Re-check it with `dvx agent get my-assistant`.
- Make sure the agent was created on a valid enclave (`--broker-id` from `dvx broker list`).
- Inspect recent output with `dvx agent logs my-assistant`. If the agent never starts provisioning, contact Daevix support - provisioning happens on the managed enclave.

### Agent starts but the bot doesn't respond

- Verify your Telegram user ID is in `--allowed-users` (re-link with `dvx agent channel telegram link` to update it).
- Check the agent's output: `dvx agent logs my-assistant`.
- Confirm the bot token is valid: `curl https://api.telegram.org/bot<token>/getMe`.

### "Forbidden" or "Conflict" errors in the agent logs

- **403 Forbidden** - the agent is suspended or isolated. Restore it with `dvx agent restore my-assistant`, or check `dvx agent get`.
- **409 Conflict** - a refresh token was replayed and the token family was revoked. Recreate the agent (`dvx agent delete` then `dvx agent create`).

### "no LLM API credential configured" from the proxy

The proxy couldn't find an LLM key for the agent. Set `llmproxy:llm.api_key` at the org level (Step 3) or an `llmproxy.api_key` override on the agent.