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.
• An LLM API key (e.g. an Anthropic key starting with sk-ant-).
• A Telegram bot token from @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.
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 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):

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

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

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

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:

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:

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.