Single Agent Setup

Deploy one purpose-built AI agent that responds to Telegram messages, hibernates when idle, and wakes on demand.

What you’ll build

A single agent that:

• Receives messages via Telegram webhook
• Processes them with an AI provider (Anthropic, OpenAI, etc.)
• Responds via the Telegram Bot API
• Hibernates when idle — costs nothing while sleeping
• Wakes automatically when the next message arrives

Prerequisites

• A LobsterCage account (sign up free )
• The lobster CLI: npm install -g lobstercage-cli
• An AI provider API key (Anthropic, OpenAI, etc.)
• A Telegram bot token (from @BotFather )

Step 1: Create a cage

lobster create my-agent

This creates a Starter-sized cage (1 vCPU, 4 GB RAM) and starts it.

For heavier workloads, choose a larger size:

lobster create my-agent --size standard   # 2 vCPU, 8 GB RAM
lobster create my-agent --size power      # 4 vCPU, 16 GB RAM

Step 2: SSH in and configure OpenClaw

OpenClaw is pre-installed in every cage. SSH in and run the interactive setup:

lobster ssh my-agent
openclaw configure

The openclaw configure wizard walks you through:

• Choosing your AI provider and entering your API key
• Entering your Telegram bot token
• Registering the webhook URL with Telegram

Follow the prompts — OpenClaw handles the configuration for you.

Step 3: Get your webhook URL

In a separate terminal, get the cage’s webhook URL:

lobster status my-agent

The output includes a Webhook URL like:

https://gateway.lobstercage.ai/hook/cage_abc123/tok_xyz789/

For Telegram, OpenClaw can register this automatically during openclaw configure. You can also register it manually:

curl -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
  -d '{"url": "YOUR_WEBHOOK_URL"}'

See the Telegram webhook guide for more details.

Step 4: Test the full lifecycle

1. Send a message to your bot on Telegram
2. Watch it respond — the AI processes your message and replies
3. Wait 30 minutes (or adjust the idle timeout) — the cage hibernates automatically
4. Send another message — the gateway buffers it, wakes the cage, delivers it
5. Check your billing — you only paid for the minutes the cage was active

# Monitor the lifecycle in real time
lobster tail my-agent
 
# Check status
lobster status my-agent

How the lifecycle works

1. User sends a message → Telegram delivers it to your webhook URL
2. Cage is hibernated? → Gateway proxy buffers the request (encrypted) and triggers a wake
3. Cage boots (~10-30 seconds) → OpenClaw auto-starts, buffered messages are delivered
4. Agent responds → AI processes the message and sends a reply via Telegram
5. No activity for 30 minutes → Cage auto-hibernates, billing stops
6. Next message arrives → Cycle repeats from step 2

OpenClaw auto-starts on every wake — once you’ve run openclaw configure, you never need to start it manually again. The cage manager detects your config and launches OpenClaw automatically.

Your agent is always reachable but you only pay for active compute time. A typical agent handling a few conversations per day costs just a few dollars per month.

Programmatic setup (for automation)

If you’re creating agents programmatically (e.g., from an orchestrator), you can skip the interactive wizard. Deploy with the openclaw-chatbot template and set env vars:

lobster create my-agent --template openclaw-chatbot
lobster env set my-agent ANTHROPIC_API_KEY=sk-ant-...
lobster env set my-agent TELEGRAM_BOT_TOKEN=123456:ABC...

The openclaw-chatbot template tells the cage manager to auto-detect the Telegram bot token from env vars and generate the OpenClaw config at boot. See the orchestrator pattern for the full programmatic workflow.

What’s next

• Add cron jobs for scheduled tasks — LobsterCage auto-wakes your cage before scheduled runs. See cron scheduling.
• Deploy a second agent — each with its own domain and personality. See multi-agent setup.
• Build an orchestrator — automate agent creation and task delegation. See the orchestrator pattern.

Tips

• Workspace persistence: Everything in /workspace and /home/agent survives hibernation. Install packages once.
• Budget controls: Set spending limits in the dashboard to prevent runaway costs.
• SSH debugging: Use lobster ssh my-agent anytime to inspect, debug, or update your agent live.
• Live logs: lobster tail my-agent streams events in real time.