Everything you need.
Before the first task.

01 / GETTING STARTED

A computer for your agent.

Runboxd provides a persistent execution environment built on standard Ubuntu virtual machines. Your external agent or configured workflow supplies the instructions. Model subscriptions and API charges are separate.

1. Sign in to the private preview. Access is limited to verified @agentboxd.com email addresses. Sign in with your eligible account; ordinary client registration is not open yet. The dashboard shows your actual allowance.
2. Choose Browser or Computer. Browser is for websites and web apps. Computer adds a managed Ubuntu desktop, terminal and user tools, and requires an allowance of at least 4 GB / 2 vCPUs. Compare both environments.
3. Start the machine. Wait until it is ready. A queued start is waiting for host capacity; it is not a failed computer and waiting time does not consume plan hours.
4. Connect an agent. In the computer’s agent-access controls, create a restricted key for that computer. Grant the profiles, folders, accounts and domains it needs, then set its expiry and action budget. Keep the key in your agent’s secret store.
5. Give it a bounded first task. Start with navigation and inspection. Add website accounts and a verification rule before allowing actions such as publishing or submitting records.

02 / WEBSITE ACCOUNTS

Save the sign-in. Keep the context.

Create a named browser profile to separate a website’s cookies and local storage from other profiles. A saved website-account recipe binds a login URL, field selectors and encrypted credentials to a profile and an exact HTTPS origin.

1. Open the website and inspect its login form. Configure the username, password and submit fields for that site.
2. Save the account through the account controls, then grant the agent access to that account, profile and domain.
3. The agent calls the saved login recipe when needed. Configure a success selector to check the authenticated page; otherwise the agent must inspect and verify the result.

Profiles survive browser close/reopen and machine restarts. Sites can still expire or revoke sessions. There is no universal login detector or background reauthentication guarantee. Cross-origin identity providers need their own recipe for the actual login origin.

Account listings return metadata, not decrypted passwords. Removing a recipe removes the saved credential record; it does not sign out a browser that is already authenticated.

03 / WORKFLOWS & EVIDENCE

Define what “finished” means.

Durable tasks retain step history, checkpoints, receipts and output artifacts. A configured workflow can open a saved account, collect information, transform a file and verify the result. Your website selectors, credentials and success rules make the workflow specific to your business.

• Research: navigate public pages, collect selected facts and retain a report with supporting evidence.
• Reporting: export a CSV from a web app, process it with supported workflow steps or Computer tools, check it and save the result.
• Publishing: fill an editor and submit approved content through the site’s interface, then check the resulting page.
• Recurring operations: save a configured task and schedule another run with a timezone, action budget and run limit.

A receipt records the configured verification result. It is not independent proof that every external system completed its work. If a submission outcome is uncertain, a task can require review instead of blindly repeating it. Check the destination before retrying a payment, publication or other action that could happen twice.

The homepage examples are product illustrations. They are not live customer results or preconnected CRM integrations. External agents can use the REST API for other workflows; native shell-based processing requires Computer.

04 / LIVE CONTROL

Keep a human in the loop.

The dashboard provides a live browser view on Browser and a desktop view on Computer. Use human takeover to handle a sign-in, review an unfamiliar page or finish an approval. Handoff coordinates with agent input, and control can be returned when you finish.

Computer also includes a terminal, file manager and user-installed tools in the home directory or workspace. It is a managed environment: customer root, sudo and SSH are not available. Native internet tools must use the supported HTTP/HTTPS proxy. The separate API shell is network-isolated and restricted.

Whole-computer agent access is available only on Computer, requires explicit consent and expires. It grants broad access inside that VM. Use a separate computer when workloads require independent desktop or shell trust boundaries.

05 / SCHEDULES & USAGE

Ready when the work returns.

Configure a recurring daily schedule with its timezone, workflow, action budget and run limit. Schedules can wake a stopped machine and begin work after it is ready. Starts enter a queue when host capacity is busy; a scheduled time is not an exact execution-time guarantee.

Computers normally stop after 15 minutes without Runboxd activity. Durable tasks report active work. A native background program does not report that activity by itself, so do not rely on it to keep the machine awake. Stop the machine when you finish to conserve plan hours.

Usage is pooled across running computers. Browser consumes half a plan hour per running hour; Computer consumes one. Stopped and queued time do not count. Allowances reset each calendar month in UTC and are enforced even during free private preview. Files persist across stops. See pricing, allowances and usage examples.

06 / SECURITY & DATA

Understand the boundary.

Machines and network access

Each customer computer runs in a separate VM. Browser traffic uses the platform’s destination policy and egress proxy. Public-web mode still blocks private addresses, host services, cloud metadata endpoints and other customers’ machines. An agent’s domain grant can narrow access further. API, browser, proxy and shell workers use separate unprivileged accounts.

Agent permissions

Restricted keys are bound to one computer and selected profiles, folders, website accounts and domains. They do not gain shared desktop or shell access as a workaround. Use expiry, budgets and revocation to control future access. Revocation does not undo an action already submitted to a website, and it does not necessarily terminate every native program started with broader Computer access.

Credentials and records

Saved credential payloads are encrypted. Their management API lists metadata rather than returning passwords. Known credential values are redacted from text responses, but screenshot pixels and the website’s own memory may still contain sensitive information. The computer owner has broader control than a restricted agent.

Tasks can retain encrypted specifications, checkpoints, receipts and artifacts. Operational audit records are append-only at the API database role. The platform runs encrypted backups. This is private preview; no audited compliance certification, uptime SLA or recovery-time guarantee is advertised.

Keeping and removing data

Stopping or restarting a machine preserves its workspace and browser profiles. Deleting a computer removes its live workspace; download needed files first. Backups have a separate lifecycle, so deletion of a live machine is not a claim of immediate erasure from every backup. Contact hello@agentboxd.com for data-handling or deletion questions.

Use accounts you are permitted to access and follow the destination website’s rules. Grant an agent permission to publish, submit or change data only when that is the work you intend.

07 / PRODUCT LIMITS

Practical limits, up front.

These are the standard current product limits. Older computer images and account-specific allowances can differ; your dashboard and API responses describe your machine.

Common forms, rich-text editors, frames, popups, link downloads and supported form/blob exports are available. Service-worker-dependent apps, arbitrary native download flows and every possible editor are not guaranteed. Website behavior and browser sessions can change independently of Runboxd.

08 / DEVELOPER API

A familiar HTTPS interface.

The public gateway is https://runboxd.com/v1/computers/{computer_id}. Send a scoped key in Authorization: Bearer …. Keep secrets out of source code, URLs and logs. Restricted agent keys operate within their assigned computer; they do not provision other computers.

First browser action

Start your computer, install the Python requests package in your agent’s environment, and supply RUNBOXD_API_KEY and RUNBOXD_COMPUTER_ID from your secret store. For this example, grant the key browser access, the research profile and the example.org domain.

import os
import requests

base = "https://runboxd.com/v1/computers/"
base += os.environ["RUNBOXD_COMPUTER_ID"]
headers = {"Authorization": "Bearer " +
           os.environ["RUNBOXD_API_KEY"]}

def action(path, payload):
    response = requests.post(
        base + path, headers=headers,
        json=payload, timeout=90)
    response.raise_for_status()
    return response.json()

action("/browser/sessions", {"profile": "research"})
result = action("/browser/navigate", {
    "session_id": "research",
    "url": "https://example.org"
})
print(result["status"])

Browser actions return a job envelope with job_id, status and result. Errors include a stable error.code and a readable message. Check both transport errors and the action outcome before continuing.

API areas

Download the control-plane OpenAPI schema for account, computer and schedule operations. Guest browser and workflow actions are forwarded through the computer gateway; the control-plane schema does not enumerate every guest action.

09 / TROUBLESHOOTING

Find the next step.

• 401 / invalid authentication: check key expiry, revocation and the Bearer header. Website credentials are separate from the Runboxd API key. For dashboard access, use sign in and the password-reset flow.
• 403 / permission denied: check the computer binding, capability scopes, profile, folder, account and domain grants. Private-network destinations remain blocked.
• Computer queued or not ready: check its dashboard state. Wait for a queued start or cancel it if the work is no longer needed. Avoid repeated start requests.
• Website login needs interaction: inspect the live page for MFA, CAPTCHA, changed fields or a session that expired. Complete the permitted step and update the recipe if the form changed.
• Monthly allowance reached: review usage in your dashboard and contact us about additional capacity. Automatic paid overages are not enabled.
• Uncertain submission: inspect the destination and retained task evidence before retrying to avoid duplicate actions.

For support, share the computer ID, approximate time and error code. Do not send passwords, API keys, session cookies or sensitive screenshot content.

AGENT CONNECTION

Connect through MCP.

Open Agents, create a restricted key for one running computer, and choose its browser profile, workspace folder and allowed website hostnames. The connection panel shown with your new key contains a configuration tailored to that agent.

On the machine running your agent, install Python 3.11 or newer and the Runboxd bridge:

python -m pip install https://runboxd.com/downloads/runboxd-mcp.zip

In your MCP client, use command python, arguments ["-m", "runboxd_mcp"], and environment settings RUNBOXD_COMPUTER_ID, RUNBOXD_TOKEN_FILE, RUNBOXD_PROFILE and RUNBOXD_FOLDER. Use an absolute path to a private token file readable only by your user. An existing secret manager can instead inject RUNBOXD_TOKEN into the process environment. Do not put the key in a prompt or command argument.

The bridge runs locally over stdio and sends requests to Runboxd over verified HTTPS. It exposes scoped browser, file and task tools. It cannot create owner keys, reveal saved passwords, approve its own publication, or change computer lifecycle. The gateway and guest enforce permissions, action allowances, expiry and revocation on every request. Model charges stay with your agent provider.

Reconnect your MCP client and ask it to call runboxd_status. A machine that is stopped or queued must become ready first. For a failed connection, check the assigned computer, key expiry and grants. python -m runboxd_mcp --check tests the same configured access without changing website data.

FIRST TASK

A useful result, with evidence.

Open Workflows and try the CSV demo on a running computer. It downloads the built-in sample data, totals customer amounts and saves a report with an expected total of 255.00. No model key or website account is required.

The catalog also supports capture of up to five exact source pages, CSV export and reconciliation, and content drafts with optional publication. Research captures at most 16,000 text characters per page and checks the page address and saved-file integrity; it does not verify the truth of the source. Publishing requires approval and a saved read-only API connection that confirms the exact content at the destination.

Review prepares a task without executing it. Permissions and destination rules are enforced when it runs. Open the computer to watch progress, handle an approval and download saved outputs. The result summary shows the recorded completion checks and action allowance. Missing model usage records do not prove an external agent incurred no cost.