Hosted Agents | EmpirioLabs AI Docs

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, 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, Poe, 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.

$ 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.

$ 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.

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 or custom to point it at your own provider.

$ 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

$ curl https://api.empiriolabs.ai/v1/hosted-agents/instances \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Get an agent

$ curl https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Send a message

$ 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.

$ curl -X POST https://api.empiriolabs.ai/v1/hosted-agents/instances/AGENT_ID/restart \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Rename an agent

$ 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

$ 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, or custom.

$ 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

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.

$ # 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:<slug>, Hermes: hermes:<id>)
$ 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.

$ 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.

$ 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.

$ 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.

$ 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 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.

Next steps

Hosted Agents API reference

Full request and response schemas for every hosted agent endpoint.

Models and pricing

Browse the models your agent can use.