> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.empiriolabs.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.empiriolabs.ai/_mcp/server. # Hosted Agents Hosted Agents give you a private agent runtime that connects to your tools and runs on EmpirioLabs models. Each agent is isolated, keeps its own persistent storage, and is reachable through the EmpirioLabs API or from your connected channels. Deploy and manage agents from the [Agents page in the dashboard](https://platform.empiriolabs.ai/dashboard/agents), or entirely through the API documented on this page. ## Why Hosted Agents #### Lives in your apps Connect Telegram, Discord, Slack, Matrix, Teams, WhatsApp, and more. #### Uses connected tools Add Gmail, Drive, GitHub, Notion, Slack, custom MCP connectors, and more. #### Runs code safely Run Python, packages, commands, and generated files in isolated sandboxes. #### Browses visually Open web pages, click, type, scroll, and save screenshots. #### Generates media Create images, video, speech, music, 3D assets, transcription, and more. #### Models, managed Use EmpirioLabs models, your Poe or OpenRouter account, or your own compatible provider. ## OpenClaw and Hermes #### OpenClaw A popular do-everything assistant. A strong default when you want a capable general agent out of the box. #### Hermes An agent that learns and remembers over time, so it gets more useful to your team the more you use it. ## Plans #### Basic 15 USD per month, or 162 USD per year (10% off). #### Pro 30 USD per month, or 324 USD per year (10% off). ## Quickstart #### Deploy an agent Choose a runtime (`openclaw` or `hermes`) and a plan, then deploy. The response includes an agent `id` and a `status`. ```bash curl https://api.empiriolabs.ai/v1/hosted-agents/instances \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "My Assistant", "agent_type": "openclaw", "plan_slug": "hosted-agent-basic" }' ``` #### Wait until it is running Poll the agent until its `status` is `running`. ```bash curl https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" ``` #### Connect and use it Send the agent a message through the API, or connect a channel and talk to it from there. ## Use your OpenRouter account An agent can run on your own [OpenRouter](https://openrouter.ai) account. Its model calls then use your OpenRouter key and are billed to your OpenRouter credits, and the agent plan is billed to your EmpirioLabs account as usual. **Connect in the dashboard.** Open the agent on the [Agents page](https://platform.empiriolabs.ai/dashboard/agents), select **Connect** on the OpenRouter tile under **Model provider**, and approve access on OpenRouter. You return to the dashboard with the agent running on OpenRouter. To use a key you already have, select **Use an API key** and paste it. When you deploy a new agent with **Your OpenRouter account** selected, the approval page opens as soon as the agent is created. **Choose a model.** The **OpenRouter model** menu lists the models on your account that support tool calling, grouped by author, with OpenRouter's Auto Router first. When you switch an agent to OpenRouter, it keeps its current model if your account offers it. **What the agent can use.** Code execution, web browsing, channels, connectors, and skills work the same on OpenRouter. The built-in media generation and web search tools run on the EmpirioLabs provider. **Switch or disconnect.** Switching providers applies immediately, without a redeploy. Disconnecting OpenRouter while it is the active provider moves the agent to EmpirioLabs models. To revoke the key itself, delete it in your [OpenRouter key settings](https://openrouter.ai/settings/keys); keys created from the dashboard are labeled with the agent's name. **Connect with the API.** Connecting a key switches the agent to OpenRouter. The key is checked with OpenRouter first and is never returned by the API. ```bash # Connect an OpenRouter key curl -X POST https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/integrations \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "kind": "openrouter_api_key", "secret": "YOUR_OPENROUTER_API_KEY" }' # Choose a model curl -X POST https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/model \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "openrouter", "model": "openrouter/auto" }' # Disconnect OpenRouter curl -X DELETE https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/integrations/openrouter \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" ``` ## Deploy and manage with the API All requests use your EmpirioLabs API key as a bearer token. The base URL is `https://api.empiriolabs.ai`, and every agent endpoint lives under `/v1/hosted-agents`. `GET /v1/hosted-agents/config` returns the available plans and runtime presets (useful for discovering valid values before deploying), and `GET /v1/hosted-agents/health` reports service health. ### Deploy an agent `agent_type` is `openclaw` or `hermes`; `plan_slug` is `hosted-agent-basic` or `hosted-agent-pro`. By default the agent runs on EmpirioLabs models; set `default_model` to choose a specific one, or `default_provider` to `poe`, `openrouter`, or `custom` to point it at your own provider. A `poe` or `openrouter` agent replies once that account is connected (see [Use your OpenRouter account](#use-your-openrouter-account)). ```bash curl https://api.empiriolabs.ai/v1/hosted-agents/instances \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "My Assistant", "agent_type": "openclaw", "plan_slug": "hosted-agent-basic", "default_model": "qwen3-7-plus" }' ``` ### List your agents ```bash curl https://api.empiriolabs.ai/v1/hosted-agents/instances \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" ``` ### Get an agent ```bash curl https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" ``` ### Send a message ```bash curl https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/message \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messages": [{ "role": "user", "content": "What is on my calendar today?" }] }' ``` ### Start, stop, restart The action is the last path segment: `start`, `stop`, `restart`, or `refresh`. ```bash curl -X POST https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/restart \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" ``` ### Rename an agent ```bash curl -X PATCH https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Renamed Assistant" }' ``` ### Delete an agent ```bash curl -X DELETE https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" ``` ## Configure every setting from the API Everything you can change in the dashboard is also controllable from the API, so you can manage agents entirely programmatically. ### Change the model or provider Switch the agent's model in place (no redeploy). `provider` is `empirio`, `poe`, `openrouter`, or `custom`. ```bash curl -X POST https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/model \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "empirio", "model": "qwen3-7-plus" }' ``` ### Skills Read activity counts for an agent with `GET /v1/hosted-agents/instances/AGENT_ID/stats`. Skills are reusable playbooks the agent follows. Search the official registry (OpenClaw uses ClawHub, Hermes uses skills.sh) and add a skill by its reference, or paste your own. ```bash # List installed skills curl https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/skills \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" # Add an official skill (OpenClaw: clawhub:, Hermes: hermes:) curl -X POST https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/skills \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "slug": "hermes:openai/skills/pdf" }' # Add your own pasted skill curl -X POST https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/skills \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "custom": { "name": "House Style", "body": "Always answer in a concise, friendly tone." } }' # Remove a skill curl -X DELETE "https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/skills?slug=hermes:openai/skills/pdf" \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" ``` ### Connectors (MCP) Attach a remote MCP server to give the agent tools and data. ```bash curl -X POST https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/mcp \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "my-tools", "url": "https://example.com/mcp" }' ``` ### Channels Connect a token-based messaging channel (for example `telegram`, `discord`, or `slack`) so people can talk to the agent there. Telegram, Discord, Slack, and Matrix work on OpenClaw and Hermes agents. Mattermost and Microsoft Teams are OpenClaw-only. WhatsApp is paired from the dashboard with a QR code instead of this token endpoint. ```bash curl -X POST https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/integrations \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "kind": "telegram", "secret": "YOUR_BOT_TOKEN" }' ``` Channel behavior controls small chat signals on each connector. By default, typing indicators and minimal processing reactions are on, read receipts are off, and live reply preview is off. Live reply preview uses platform-native edit or draft preview support where available; it is separate from model API streaming. ```bash curl -X POST https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/integrations/telegram/behavior \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "behavior": { "reaction_level": "minimal", "typing": true, "read_receipts": false, "streaming": false } }' ``` ### Who can message the bot `mode` is `open` (anyone) or `restricted` (only the messaging IDs you allow). With `restricted` and no IDs, the first person to message becomes the owner. Include `kind` to set the rule for one connected channel. ```bash curl -X POST https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/access \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "kind": "telegram", "mode": "restricted", "allow": { "telegram": ["123456789"] } }' ``` ## Pricing Hosted Agents are billed per agent based on the plan you choose. Basic is 15 USD per month and Pro is 30 USD per month. Annual billing is available at 10% off: Basic is 162 USD per year and Pro is 324 USD per year. The plan covers the agent runtime and is charged to your account balance now and automatically each billing period. If a renewal cannot be covered the agent pauses until you top up, then resumes automatically. You can cancel anytime from the dashboard: the agent keeps running until the end of the period you paid for, then stops with no further charge. Models the agent uses are billed separately at standard model rates. ## Limits Each account can run a limited number of deployed agents at once. Your dashboard settings show your effective limit. [Contact us](mailto:support@empiriolabs.ai) to raise your limit. ## White-labeling You can build hosted agents into your own product and run them fully under your own brand. The API is unbranded: you call `/v1/hosted-agents/*` with your EmpirioLabs API key and surface the agent however you want, so your end users interact with your product, not ours. There is no EmpirioLabs branding in the API responses or in the agent's replies. For higher agent limits, dedicated capacity, or a custom commercial arrangement, email [support@empiriolabs.ai](mailto:support@empiriolabs.ai). ## Next steps #### [Hosted Agents API reference](/api-reference) Full request and response schemas for every hosted agent endpoint. #### [Models and pricing](/models-pricing) Browse the models your agent can use.