Self Hosting

Self-hosting means you run the worker (your agent code) on your own infrastructure instead of Zero Runtime Cloud. The runtime still handles transport, GPUs, STT/LLM/TTS orchestration, and turn-taking, so there’s no media infrastructure for you to operate. When your process calls zeroruntime.serve(...), it opens an outbound connection to the runtime and registers your agent under the id in ZERORUNTIME_AGENT_ID. The runtime then dispatches sessions for that id to every registered worker and load-balances across them.

The CLI commands under Operate (up, version, secrets, logs, down) manage workers on Zero Runtime Cloud. They don’t apply here; use your own platform for rollouts, secrets, scaling, and logs.

Prerequisites

An agent project whose main.py calls zeroruntime.serve(...). Every quickstart example does.
Docker on the machine that builds the image (and on the host that runs it, for Docker).
For Kubernetes: a cluster, kubectl configured for it, and a container registry the cluster can pull from.
Your auth token from the Zero Runtime dashboard.

Choose an agent ID

On Zero Runtime Cloud, the platform assigns the agent ID for you. When you self-host, you choose it and set it as ZERORUNTIME_AGENT_ID. The worker registers under this ID, and everything that reaches your agent targets it: zeroruntime invoke --agent-id, the dispatch API, and telephony routing rules. Pick an ID that is:

Unique: don’t reuse it for a different agent. Workers that share an ID receive each other’s sessions.
Stable: a fixed name like support-agent, not a random value generated per run or per container. Every replica of the same agent uses the same ID; that’s how the runtime load-balances across them.

If ZERORUNTIME_AGENT_ID is unset, the worker registers as zeroruntime_agent. Sessions and calls aimed at your real ID then never reach it. Always set it explicitly.

Configure the environment

The worker reads its agent ID, connection details, and provider keys from environment variables. Create a .env file in your project folder. See Authentication for the full list.

.env

ZERORUNTIME_AGENT_ID=support-agent
ZERORUNTIME_TARGET=us2.zeroruntime.ai:443
ZERORUNTIME_AUTH_TOKEN=<token>

# Configure an API key for each provider you use. Not required when using inference.
DEEPGRAM_API_KEY=<key>
GOOGLE_API_KEY=<key>
CARTESIA_API_KEY=<key>

Keep comments on their own lines. docker run --env-file and kubectl --from-env-file don’t strip trailing # comments, so they’d become part of the value.

Pass these at runtime. Don’t bake them into the image: add .env to .dockerignore.

.dockerignore

.env
.venv/
__pycache__/

Remove the local test invoke

For local testing, use the on_ready callback in serve() to start a playground session when the worker is ready. Remove it in production to avoid automatically creating a new room for every worker. In production, start sessions via zeroruntime invoke CLI, the dispatch API, or telephony routing rules.

def invoke_agent():  
    zeroruntime.invoke(room=Room(playground=True))  

if __name__ == "__main__":
    zeroruntime.serve(MyVoiceAgent, on_ready=invoke_agent)  
    zeroruntime.serve(MyVoiceAgent)  

await zeroruntime.serve(MyVoiceAgent, { 
  on_ready: () => zeroruntime.invoke({ room: Room({ playground: true }) }), 
}); 
await zeroruntime.serve(MyVoiceAgent, {}); 

Build the image

Use the Dockerfile that zeroruntime init generates, or write your own. It should install requirements.txt and run python main.py:

Dockerfile

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "main.py"]

Then build it from your project folder:

docker build -t my-agent:v0.0 .

Run the worker

Docker
Kubernetes

Start the container

Run the worker in the background, load your .env, and restart it if it exits:

docker run -d --name my-agent \
  --restart unless-stopped \
  --env-file .env \
  -p 8081:8081 \
  my-agent:v0.0

The worker only dials out to the runtime. -p 8081:8081 is optional and only exposes the health endpoint.

Confirm it registered

Check the logs for a successful connection and registration under your agent ID:

docker logs -f my-agent

Then check the health endpoint:

curl http://localhost:8081/health

Add more workers (optional)

To handle more concurrent sessions, start more containers with the same .env. Use a unique container name and host port for each:

docker run -d --name my-agent-2 --restart unless-stopped \
  --env-file .env -p 8082:8081 my-agent:v0.0

Both workers register under the same agent ID, and the runtime balances sessions across them.

Ship an update

Build a new tag, then replace the running container:

docker build -t my-agent:v0.1 .
docker stop my-agent && docker rm my-agent
docker run -d --name my-agent --restart unless-stopped \
  --env-file .env -p 8081:8081 my-agent:v0.1

docker stop sends SIGTERM and waits 10 seconds by default. Raise it with docker stop -t <seconds> if your sessions need longer to wrap up.

Push the image to a registry

The cluster must be able to pull the image. Tag it for your registry and push it:

docker tag my-agent:v0.0 registry.example.com/my-agent:v0.0
docker push registry.example.com/my-agent:v0.0

If your registry is private, create an image pull secret and reference it under imagePullSecrets in the Deployment.

Create a namespace

kubectl create namespace zeroruntime

Store your environment as a Secret

Create a Secret from the same .env file, including ZERORUNTIME_AGENT_ID:

kubectl create secret generic my-agent-secrets \
  --namespace zeroruntime \
  --from-env-file=.env

Create the Deployment

The worker is stateless, so a plain Deployment works. Every replica loads the same Secret, so all of them register under the same agent ID:

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-agent
  namespace: zeroruntime
spec:
  replicas: 3
  selector:
    matchLabels: { app: my-agent }
  template:
    metadata:
      labels: { app: my-agent }
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: worker
          image: registry.example.com/my-agent:v0.0
          envFrom:
            - secretRef:
                name: my-agent-secrets
          ports:
            - containerPort: 8081
              name: health
          livenessProbe:
            httpGet: { path: /health, port: 8081 }
            initialDelaySeconds: 10
            periodSeconds: 15

You don’t need a Service or Ingress: the worker only dials out.

Apply it and confirm the rollout

kubectl apply -f deployment.yaml
kubectl rollout status deployment/my-agent -n zeroruntime
kubectl get pods -n zeroruntime -l app=my-agent

Check that the workers connected and registered:

kubectl logs -n zeroruntime -l app=my-agent --tail=50

Scale

Change the replica count to match your traffic:

kubectl scale deployment/my-agent -n zeroruntime --replicas=5

Ship an update

Push a new tag and point the Deployment at it. Kubernetes rolls the pods one by one:

docker build -t registry.example.com/my-agent:v0.1 .
docker push registry.example.com/my-agent:v0.1
kubectl set image deployment/my-agent \
  worker=registry.example.com/my-agent:v0.1 -n zeroruntime
kubectl rollout status deployment/my-agent -n zeroruntime

To change credentials, update the Secret and restart the pods so they pick up the new values:

kubectl create secret generic my-agent-secrets -n zeroruntime \
  --from-env-file=.env --dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment/my-agent -n zeroruntime

Start a session

Self-hosted workers receive sessions the same way cloud workers do. Start one with the CLI, passing your ZERORUNTIME_AGENT_ID:

zeroruntime invoke --agent-id support-agent

The CLI prints a playground link you can open to talk to your agent.

Connect telephony

To take or place phone calls, configure gateways and a routing rule that point at your agent. Use your ZERORUNTIME_AGENT_ID wherever an agent ID is required; it must match exactly, or calls never reach your workers.

Set up inbound calls

1. Create an inbound gateway: the entry point for incoming calls.

Dashboard
API

Copy the Inbound URL from the Zero Runtime dashboard.
Go to Twilio and create a new SIP Trunk.
Go to the Origination section, paste the Inbound URL there, and save it.

curl --request POST \
  --url https://api.videosdk.live/v2/sip/inbound-gateways \
  --header 'Authorization: YOUR_ZERORUNTIME_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "My Inbound Gateway", "numbers": ["+1234567890"] }'

Then set the origination URI of your Twilio SIP trunk to the inbound gateway hostname (shown in the dashboard), e.g. sip:9WXXXXXXX.sip.videosdk.live.

2. Create a routing rule: connects the inbound gateway to your self-hosted agent.

Dashboard
API

From your inbound gateway, click Configure rule, then Create new routing rule.
Enter a Routing Rule Name and select API Key authentication.
Choose the Call Direction (Inbound).
Enter the Phone Number and select a Room Type.
Enter your ZERORUNTIME_AGENT_ID as the Agent ID and click Save.

curl --request POST \
  --url https://api.videosdk.live/v2/sip/routing-rule \
  --header 'Authorization: YOUR_ZERORUNTIME_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "gatewayId": "gateway_in_123456789",
    "name": "Support Line Rule",
    "numbers": ["+1234567890"],
    "agentId": "support-agent"
  }'

3. Test it: with your workers running, dial your provider’s phone number from any phone. The agent greets you as soon as the call connects.

Using a different SIP provider? Follow its inbound setup: Telnyx, Vonage, or Plivo.

Set up outbound calls

1. Create an outbound gateway: lets the agent dial out to the PSTN.

Dashboard
API

In Twilio, open your SIP Trunk and go to the Termination section. Create a Termination URI and add username/password credentials.
Back in the Zero Runtime Dashboard, open the outbound gateway configuration.
Paste the Twilio Termination URI as the address, add the same username/password credentials, and save.

curl --request POST \
  --url https://api.videosdk.live/v2/sip/outbound-gateways \
  --header 'Authorization: YOUR_ZERORUNTIME_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Outbound Gateway",
    "numbers": ["+12065551234"],
    "address": "sip.myprovider.com",
    "transport": "udp",
    "auth": { "username": "your-username", "password": "your-password" }
  }'

Set address and auth to match your Twilio Termination URI and credentials so outbound calls reach the PSTN.

2. Place a call: with your workers running, trigger a call from the agent. Replace YOUR_ZERORUNTIME_AUTH_TOKEN and routingRuleId with your own.

curl --request POST \
  --url https://api.videosdk.live/v2/sip/call \
  --header 'Authorization: YOUR_ZERORUNTIME_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "sipCallFrom": "+14155550100",
    "sipCallTo": "+14155550199",
    "routingRuleId": "rr_2554md"
  }'

For lower latency, run your workers in the same region as your SIP provider.

Using a different SIP provider? Follow its outbound setup: Telnyx, Vonage, or Plivo.

Operating self-hosted workers

Capacity: each worker accepts up to capacity concurrent sessions (default 10, set in zeroruntime.serve(...) or with ZERORUNTIME_MAX_CONCURRENT_SESSIONS). Add workers or replicas when you need more.
Health: each worker serves GET /health on port 8081 for liveness probes.
Rolling updates: build a new image tag and roll it out with your platform’s usual deploy process.
Credentials: rotate tokens and provider keys in your secret manager, then restart the workers so they pick up the new values.
Logs: workers log to stdout and stderr. Collect them with your existing logging stack.

Troubleshooting

Sessions or calls never arrive: the agentId in invoke, dispatch, or your routing rule doesn’t exactly match ZERORUNTIME_AGENT_ID, or the variable is unset and the worker registered as zeroruntime_agent. Check the worker logs for the ID it registered under.
Worker can’t connect: check ZERORUNTIME_TARGET and ZERORUNTIME_AUTH_TOKEN, and that outbound traffic to the runtime on port 443 is allowed.
Pods restart in a loop: check kubectl logs for a startup error, and raise the probe’s initialDelaySeconds if the worker takes longer to start.

Overview

Build

Plugins

Deploy

Prerequisites

Choose an agent ID

Configure the environment

Remove the local test invoke

Build the image

Run the worker

Start a session

Connect telephony

Operating self-hosted workers

Troubleshooting

​Prerequisites

​Choose an agent ID

​Configure the environment

​Remove the local test invoke

​Build the image

​Run the worker

​Start a session

​Connect telephony

​Operating self-hosted workers

​Troubleshooting

Prerequisites

Choose an agent ID

Configure the environment

Remove the local test invoke

Build the image

Run the worker

Start a session

Connect telephony

Operating self-hosted workers

Troubleshooting