Developer portal

How to drive this platform from another program: create an application, deploy a compose file to it, and read back the address the result answers on.

Pages 1 to 4 are the contract for a machine consumer. That means a service which manages applications on somebody's behalf, continuously, with no person at the keyboard for any given call. An API token reaches every part of it, and you need nothing else. There is no session, no cross-site request forgery token, and no HTML in the path.

Sign in with someones.computer is the exception, and says so. It authenticates a person, from your own site, so its credential is an OpenID Connect client rather than an API token, and the flow runs in their browser.

Examples using {{ example:… }} are a test

Any request or response body written as an {{ example:… }} placeholder isn't written by hand. It's a fixture under app/tests/contracts/api/, compared byte-for-byte against a live response by the test suite, and this portal renders the same file. A documented example that stopped being true is a failing build rather than a page nobody noticed—the same technique the /health contract already uses after a documented shape and an asserted shape drifted apart for a day.

That means you can copy one of those and expect it to match what you get, down to the null fields. Not every body on these pages goes through the placeholder yet—Applications and deploys still has two hand-typed request bodies with no backing fixture—so treat a body without the placeholder as illustrative rather than asserted.

For AI agents

An AI agent asked to "use someones.computer" starts at /llms.txt (prose) or /.well-known/mcp.json (the same facts as data). Neither needs a credential. Both point at the Model Context Protocol (MCP) endpoint (/_mcp) and the device-authorization flow that gets a first ApiToken without a human ever pasting one by hand. A Claude Code skill that drives the whole sequence lives at clients/claude-code-skill in the main repo. See docs/mcp.md in the main repo for the full tool surface and the token-bootstrap sequence.

A client with a native "Add Connector" button (Claude Desktop, Claude Code) doesn't need the device flow at all: /_mcp also answers as an OAuth 2.1 protected resource—point the connector at this platform's origin and it registers and authorizes itself. See docs/mcp-oauth.md in the main repo.

The shape of the API

Two prefixes, both bearer-token only:

API Platform's /api also exists—a bearer token reaches it too, since #1418. But it's a different, JSON-LD/Hydra-shaped surface describing the same resources, not an alternative path to /cli. It exists to be machine-readable (OpenAPI 3, /api/docs) rather than hand-documented, and is what the generated client SDKs below are generated from.

Existing clients

Four consumers already speak the /cli contract, if writing your own is more than you need: the sc CLI, sc-tray (the menu-bar client), the Terraform/OpenTofu provider (declarative applications, variables, managed services and bindings), and the PR-environment GitHub/Forgejo Action (a composite action wrapping sc deploy/sc stop for one job per repo). None of the four use /api—they predate it, and /cli remains the contract this portal documents by hand.

Client SDKs

Four generated clients for /api—not /cli—one per language, each its own repo:

Every operation takes the same bearer ApiToken as /cli—see Authentication. /sdks is the public page for these (install snippets, links, one mascot per language); see docs/sdk-generation.md in the main repo for how they're generated and regenerated, and their current rough edges (default-generated method names, not yet published to a package registry).

Base URL and versioning

Every path on these pages is relative to the install you are talking to — https://someones.computer for the public one. There is no version prefix. The contract grows by adding fields. A consumer must ignore fields it doesn't recognise rather than failing on them, because new ones will appear.