Building an Autonomous Agent That Finishes a Task with /v1/runs
You have multi-step work that spans real desktops, browsers, and terminals. You cannot express it as a simple set of API calls or brittle CSS selectors. You need an agent that sees the screen, interprets instructions, and acts like a human. The /v1/runs endpoint is the simplest way to spawn such an agent and let the server drive it to completion.
How /v1/runs works
POST /v1/runs starts a task run. The body includes machine_id, task, and cua_version. cua_version defaults to v3; use v4 for an autonomous run with a pass/fail verifier. You can append your own instructions, provide a system_prompt, set max_steps, deadline_seconds, and decide what to do when the agent needs human approval: pause, fail, or cancel. You can also supply a webhook_url for async notifications. The server runs an agent that captures screenshots, predicts actions, and executes them until status becomes done, succeeded, failed, cancelled, or timed out. You are billed $0.05 per agent step.
#!/usr/bin/env bash
# Set your API key from the environment
export COASTY_API_KEY="$(cat ~/.coasty/key 2>/dev/null || env | grep COASTY_API_KEY | cut -d= -f2)"
if [ -z "$COASTY_API_KEY" ]; then
echo "Error: set COASTY_API_KEY"
exit 1
fi
# Start an autonomous task run
# - machine_id: ID of the cloud VM to use
# - task: high-level goal for the agent
# - cua_version: v4 for autonomous with pass/fail
# - max_steps: limit steps to avoid runaway runs
# - on_awaiting_human: pause on human approval
# - webhook_url: optional callback for events
curl -sS https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "vm-12345",
"task": "Open Chrome, navigate to https://example.com, take a screenshot, paste text into the search box, and submit the form.",
"cua_version": "v4",
"max_steps": 30,
"deadline_seconds": 300,
"on_awaiting_human": "pause",
"webhook_url": "https://your-server.com/coasty-events"
}' | jq .Check run status and events
- ●GET /v1/runs returns a list of runs with id, status, and other metadata.
- ●GET /v1/runs/{id} returns detailed information about a specific run.
- ●GET /v1/runs/{id}/events streams Server-Sent Events; store Last-Event-ID for reconnection.
- ●States: queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
Spawn a run with POST /v1/runs. Read status from GET /v1/runs/{id} and events from GET /v1/runs/{id}/events.
Where this beats brittle automation
Traditional automation relies on fixed selectors, XPath, or undocumented API endpoints. When layouts change, tests break. With a computer use agent, you give the agent a high-level goal, and it sees the current screen state. It can adapt to UI changes, handle popups, and work in real browsers and terminals. You do not need to maintain a library of brittle selectors. You just describe what needs to happen, and the agent acts for you.
You can now spin up autonomous agents that finish complex tasks on real desktops. Try a simple run with POST /v1/runs, then explore workflows for multi-step pipelines. Get your API key at https://coasty.ai/developers and start building your first computer use agent.