Docshost()

host()

Make your agent accessible over the network. One function call. HTTP, WebSocket, and P2P relay.

Why host()? Turn local agents into network services. HTTP API, WebSocket, P2P relay - all with one function call.

60-Second Quick Start

Create an agent and call host(agent) - that's it:

host_agent.py

from connectonion import Agent, host

agent = Agent("translator", tools=[translate])

# Make it network-accessible
host(agent)

Python REPL

Interactive

╭─────────────────────────────────────────────────────────╮

│ Agent 'translator' is now hosted │

├─────────────────────────────────────────────────────────┤

│ │

│ Address: 0x3d4017c3e843895a92b70aa74d1b7ebc9c98... │

│ │

│ HTTP Endpoints: │

│ POST http://localhost:8000/input │

│ GET http://localhost:8000/sessions/{session_id} │

│ GET http://localhost:8000/health │

│ WS ws://localhost:8000/ws │

│ │

│ Interactive UI: │

│ http://localhost:8000/docs │

│ │

│ P2P Relay: │

│ wss://oo.openonion.ai/ws/announce │

│ │

╰─────────────────────────────────────────────────────────╯

Waiting for tasks...

What You Get

HTTP API → POST /input, GET /sessions, GET /health

WebSocket → Real-time streaming at /ws

Interactive UI → Test your agent at /docs

P2P Relay → Connect from anywhere via relay

Worker Isolation

Each request gets a fresh deep copy of your agent:

No shared state between concurrent requests

Stateful tools work correctly (browser, file handles)

Complete isolation - one request can't affect another

HTTP API

POST /input - Submit a Task

code

curl -X POST http://localhost:8000/input \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Translate hello to Spanish"}'

Python REPL

Interactive

{

"session_id": "550e8400-e29b-41d4-a716-446655440000",

"status": "done",

"result": "Hola",

"duration_ms": 1250,

"session": {...}

}

Multi-turn Conversations

Pass the session from the response to continue:

main.py

# First request
response = requests.post("http://localhost:8000/input", json={
    "prompt": "My name is John"
})
session = response.json()["session"]

# Second request - pass session back
response = requests.post("http://localhost:8000/input", json={
    "prompt": "What is my name?",
    "session": session  # Agent remembers!
})
print(response.json()["result"])  # "Your name is John"

GET /sessions/{session_id} - Fetch Results

code

curl http://localhost:8000/sessions/550e8400-e29b-41d4-a716-446655440000

Python REPL

Interactive

{

"session_id": "550e8400-...",

"status": "done",

"result": "Hola",

"duration_ms": 1250

}

GET /sessions - List Sessions

code

curl http://localhost:8000/sessions

Python REPL

Interactive

{

"sessions": [

{"session_id": "abc-123", "status": "done", "created": 1702234567},

{"session_id": "def-456", "status": "running", "created": 1702234570}

]

}

GET /health - Health Check

code

curl http://localhost:8000/health

Python REPL

Interactive

{

"status": "healthy",

"agent": "translator",

"uptime": 3600

}

GET /info - Agent Info

code

curl http://localhost:8000/info

Python REPL

Interactive

{

"name": "translator",

"address": "0x3d4017c3...",

"tools": ["translate", "detect_language"],

"trust": "careful",

"version": "0.5.10"

}

WebSocket API

Real-time communication with streaming support:

app.js

const ws = new WebSocket("ws://localhost:8000/ws");

ws.send(JSON.stringify({
  type: "INPUT",
  prompt: "Translate hello to Spanish"
}));

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "OUTPUT") {
    console.log("Result:", msg.result);
  } else if (msg.type === "STREAM") {
    process.stdout.write(msg.chunk);
  }
};

INPUT → Agent

Send prompts to the agent

OUTPUT ← Agent

Receive final results

STREAM ← Agent

Streaming chunks

ERROR ← Agent

Error messages

Trust & Access Control

Control who can access your agent:

Trust Levels

main.py

host(agent, trust="open")      # Accept all (development)
host(agent, trust="careful")   # Recommend signature (default)
host(agent, trust="strict")    # Require signature (production)

Access Lists

main.py

host(agent,
    blacklist=["0xbad..."],   # Always reject
    whitelist=["0xgood..."]   # Always accept
)

Natural Language Policy

main.py

host(agent, trust="""
I trust requests that:
- Come from known contacts with good history
- Have valid signatures
- Are on my whitelist OR from local network
""")

Configuration

All Parameters

main.py

host(
    agent,
    trust="careful",           # Trust level/policy/agent
    blacklist=None,            # Addresses to reject
    whitelist=None,            # Addresses to accept
    port=8000,                 # HTTP port
    workers=1,                 # Worker processes
    result_ttl=86400,          # Result storage (24h)
    relay_url="wss://...",     # P2P relay
    reload=False               # Auto-reload on changes
)

Development vs Production

Development

main.py

host(agent, reload=True, trust="open")

Production

main.py

host(agent, workers=4, trust="strict")

API Reference

Parameter	Type	Default	Description
agent	Agent	required	The agent to host
trust	str \| Agent	"careful"	Trust level, policy, or agent
blacklist	list	None	Addresses to always reject
whitelist	list	None	Addresses to always accept
port	int	8000	HTTP server port
workers	int	1	Number of worker processes
result_ttl	int	86400	Result storage TTL (24h default)
relay_url	str	production	P2P relay server URL
reload	bool	False	Auto-reload on code changes

Deployment

With Uvicorn/Gunicorn

main.py

# myagent.py
from connectonion import Agent, host

agent = Agent("translator", tools=[translate])
app = host.app(agent)  # Export ASGI app

if __name__ == "__main__":
    host(agent)

code

# Run with uvicorn
uvicorn myagent:app --workers 4

# Or gunicorn
gunicorn myagent:app -w 4 -k uvicorn.workers.UvicornWorker

Docker

code

FROM python:3.11-slim
RUN pip install connectonion
COPY myagent.py .
CMD ["python", "myagent.py"]

Docker Compose

code

# docker-compose.yml
services:
  agent:
    build: .
    ports:
      - "8000:8000"
    environment:
      - CONNECTONION_ENV=production
      - OPENAI_API_KEY=${OPENAI_API_KEY}

systemd Service

code

# /etc/systemd/system/myagent.service
[Unit]
Description=My ConnectOnion Agent
After=network.target

[Service]
User=app
WorkingDirectory=/app
ExecStart=/usr/bin/python myagent.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

code

sudo systemctl enable myagent
sudo systemctl start myagent

Ready to Host Your Agents?

Just call host(agent) and your agent goes live!

Connect to Agents Learn About Agents

Plugin System

Connect to Agents