Hosted Agents (Cloud Runners)

Hosted agents (cloud runners) let you execute commands in isolated cloud containers without installing or managing an agent on your own machine. From the caller’s perspective, everything works identically to self-hosted endpoints — same API, same SSE streaming, same auth.

How it works

Self-hosted:  POST /v1/user/endpoint → API → Tunnel → Agent WS → your machine
Hosted:       POST /v1/user/endpoint → API → Redis job queue → Worker → Docker container

Same URL, same API key, same response format. The only difference is where the command runs.

Requirements

• Pro or Team plan — hosted runners are not available on the free tier
• No agent installation needed for hosted endpoints

Setting up a hosted endpoint

Set the agent_name to hosted when creating or editing an endpoint:

In the dashboard

1. Go to Endpoints → create or edit an endpoint
2. In the Agent dropdown, select Cloud Runner
3. Configure your command, parameters, and other settings as usual
4. Save the endpoint

In wrapd.yaml

endpoints:
  - slug: my-hosted-task
    command: "python3 /workspace/script.py"
    agent_name: hosted
    description: Runs on cloud runner

Via API

curl -X POST https://api.wrapd.sh/endpoints \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-hosted-task",
    "command": "echo hello from the cloud",
    "agent_name": "hosted"
  }'

Calling a hosted endpoint

Calling a hosted endpoint is identical to calling a self-hosted one:

curl -N https://api.wrapd.sh/v1/youruser/my-hosted-task \
  -H "X-API-Key: your-api-key"

Container environment

Each execution runs in a fresh, ephemeral Docker container with:

• Base image: wrapd/runner:base (Debian with bash, curl, jq, git, python3, node)
• Read-only rootfs with tmpfs at /tmp and /output (100 MB each)
• No network access by default (--network=none)
• /workspace as working directory
• PID limit: 256 (prevents fork bombs)
• Runs as non-root runner user

Resource limits by tier

	Pro	Team
CPU	1 vCPU	2 vCPU
Memory	512 MB	2 GB
Timeout	120s	300s
Concurrent	5	20
Executions/month	5,000	50,000

Secrets injection

Managed secrets are automatically injected as environment variables into hosted containers, just like self-hosted agents.

Mixing hosted and self-hosted

You can mix both in the same account — some endpoints on your agent, some on cloud runners. In pipelines, individual steps can target different agents:

Step 1: "build"  → agent_name: hosted    (cloud runner)
Step 2: "test"   → agent_name: default   (your machine)
Step 3: "deploy" → agent_name: hosted    (cloud runner)

Pipeline shared volumes

When hosted endpoints run as part of a pipeline, all hosted steps in the same run share a volume at /workspace. This means step 2 can read files that step 1 wrote — no need to pipe everything through stdout.

Monitoring usage

View your hosted execution usage in the Agents page under the Cloud Runner card. The usage bar shows your current month’s executions vs. your tier limit.

You can also query usage via the API:

curl https://api.wrapd.sh/hosted/usage \
  -H "Authorization: Bearer $TOKEN"