# Agents as First-Class Users ORB is a deployment platform whose primary user is an AI agent, not a human. Most developer tools assume a human at a browser. Sign up on a marketing page. Click "New Project." Paste an SSH key. Install a CLI. Approve an OAuth prompt. Connect a repo. Every step is a form the human fills in. ORB is the inverse. Every capability is an HTTP endpoint the agent calls directly. Every input the agent needs has a documented source it can read from the local machine. Every piece of documentation is written for an agent to ingest in one shot. When a human uses ORB, they tell their agent to use ORB. The agent does everything else. ## What this means concretely ### 1. Docs are agent-first, not human-first is the canonical reference. It's a single page, no JavaScript, no anchor jumping, no tabs. Every endpoint, every field, every example, plain text, no frills. An agent curls it once and has the whole surface. The HTML docs exist for humans who wander in. The llm.txt is the spec. ### 2. Config is declarative, not programmatic No Python SDK. No JavaScript SDK. No `from orb import Computer; c = Computer(...)`. Instead: `orb.toml`. A single config file the agent writes. A POST uploads it. ORB reads it. No library to learn, no versions to track, no `pip install` to manage. The agent already knows how to write TOML. It doesn't need to learn our API shape beyond "POST this file to this endpoint." ### 3. Every interface is plain HTTP + JSON Authorization is `Authorization: Bearer orb_...`. Nothing else. No OAuth dance, no JWT refresh, no session cookies, no CSRF tokens. An agent that can call `curl` has full access. Request bodies are JSON. Responses are JSON. Errors are JSON with an `error` field and an HTTP status. Any language that can speak HTTP can drive ORB. ### 4. Credentials the agent reads, not credentials we store For auto-deploy, ORB doesn't ask for a long-lived "GitHub integration token" it holds onto. The agent grabs a token from its local environment (`gh auth token`), POSTs it to us, we use it once, we discard it. This isn't laziness on our part, it's a security posture. The fewer credentials we hold, the smaller our breach blast radius. The agent's machine already has secure storage for its tokens. We don't need a second copy. See [Auto-Deploy on Git Push](guides/auto-deploy.md) for the use-and-discard PAT flow. ### 5. The agent can bootstrap itself An agent with zero prior ORB state can do all of the following with only the ORB API: - Create its own ORB account: `POST /api/v1/auth/register`, self-serve, no human approval, no payment upfront. Returns an `orb_…` key, ready to use. - Create a computer: `POST /v1/computers`. - Write `orb.toml`, upload it: `POST /v1/computers/{id}/config`. - Build, deploy: two more POSTs. - Wire up auto-deploy: one more POST. - Rotate the key if compromised: `POST /v1/keys/{key_id}/rotate`, atomic, no downtime. No dashboard visits, no OAuth redirects, no human in the loop at any step. An agent reading has everything it needs. ### 5a. Humans can sign in, but the handoff is still pure API Humans who land on orbcloud.dev and click "Sign in with GitHub" get an `orb_…` key **and a ready-to-paste prompt** containing that key plus the one-page reference URL. They copy the prompt into Claude Code, Codex, Cursor, Cline, Aider, OpenClaw, any agent. From that point on, the flow is identical to the self-register path: one `Authorization: Bearer orb_…` header, JSON in, JSON out. The agent doesn't know (or care) whether a human typed something into a browser at some point. The handoff is the only human-shaped moment in the whole flow. ### 6. Errors are actionable, not decorative When a build fails, we return the stderr. When a PAT is missing a scope, we tell the agent which scope. When a computer doesn't exist, we say so, we don't hide it behind a generic 500. Agents read error messages and retry intelligently. We give them messages worth reading. ## What ORB does not assume - That a human is watching. We never block waiting for an interactive confirmation. - That the agent has browser access. Every flow is completable with `curl`. - That the agent has ever used ORB before. Every endpoint is self-describing; llm.txt teaches the whole model. - That the agent speaks a specific language. No SDK means no language preference. - That the agent will remember anything. Every call is idempotent where it makes sense (uploading config overwrites; bootstrap overwrites the workflow file; create-on-conflict returns the existing resource). ## What humans get anyway Nothing about this makes ORB worse for humans. The HTML docs, the dashboard, the terminal-in-the-browser, the UI pricing calculator, all there, all work. But none of them are load-bearing. If we shut off every human-facing surface tomorrow, an agent could still drive ORB end-to-end. That's the test. ## How this maps to the product - **Deploy:** [getting-started.md](getting-started.md), every step is a `curl`. - **Config:** [config-reference.md](config-reference.md) + [llm.txt](/llm.txt), the full orb.toml schema. - **API:** [api-reference.md](api-reference.md), every endpoint. - **Auto-deploy:** [guides/auto-deploy.md](guides/auto-deploy.md), use-and-discard PAT, no stored credentials. The docs are the UI. The agent is the user.