Building an app

An app is an HTTP service you run, on your own domain, with your own database. Spunto knows three things about it: a base URL, a signing secret Spunto gives you when you register it, and the manifest the app serves. Everything else — the tokens it obtains, the accounts it connects, the machines it runs — stays with the app.

This is not a simplified version of how first-party integrations work. GitHub (git), Google Cloud (runtime) and the machines-you-bring runtime are separate services that speak exactly this contract; nothing on this page is reserved to them.

The objects

Installations belong to organizations on purpose: what an app produces — a clone credential, a machine — belongs to the organization, and must keep working when the person who connected it leaves. A grant is the exception, not half the model.

What your app serves

Signed calls carry an HMAC over the method, the path and the body → Signed requests.

The manifest

GET /manifest

{
  "id": "acme-git",
  "name": "Acme Git",
  "description": "Repositories hosted on Acme Git.",
  "publisher": "Acme",
  "accent": "#2563eb",
  "auth": "oauth",
  "capabilities": [
    {
      "capability": "git",
      "operations": ["cloneCredential", "listRepos", "listBranches", "userCredential"]
    }
  ],
  "userGrantOperations": ["userCredential"],
  "publicUrl": "https://git.acme.dev/spunto",
  "installPath": "/oauth/install",
  "grantPath": "/oauth/user",
  "managePath": "/settings"
}

Spunto re-reads the manifest every minute. Adding an operation to your app is a deploy of your app — no release of Spunto, and the buttons that depend on it appear on their own.

Optional operations are the point

The dashboard shows a feature if and only if an installed app implements the operation behind it. A git host without registerUserSshKey still clones — members simply aren't offered to register their key with it. A runtime without pause still runs sandboxes — the Pause button is simply not there. Declare what you implement, nothing more, and the product adapts.

Installing: launch, stage, confirm

A browser redirect authenticates nobody. So the parameters of an installation are never taken from a query string: Spunto signs them, and confirms the result server to server.

// POST /oauth/complete — signed
{ "orgId": "org_…", "userId": "usr_…", "completion": "c8f1…", "canInstall": true }
 
// 200
{ "result": { "kind": "install" } }   // or "grant"

The confirmation step is what makes a forwarded link harmless: an attacker who sends their launch link to someone else cannot attach that person's account to the attacker's organization, because the user Spunto confirms with is whoever is really signed in.

A grant follows the same four steps, starting from grantPath with a launch token whose purpose is grant, and committing for that one member.

Status: Spunto asks, it does not know

Spunto holds no copy of what an organization connected. To draw the Integrations page it asks:

// POST /status — signed
{ "orgId": "org_…", "userId": "usr_…" }
 
// 200
{
  "result": {
    "installations": [
      {
        "externalId": "48213",
        "accountLogin": "acme",
        "accountType": "Organization",
        "accountAvatarUrl": "https://…",
        "installedAt": "2026-10-02T09:14:00Z"
      }
    ],
    "grant": { "present": false, "externalId": null }
  }
}

Always return grant, even if your app has no grants — { "present": false, "externalId": null }. Disconnecting happens in your app (on your managePath, say); the next /status is how Spunto finds out.

Capability calls

Every operation is one signed POST, with one envelope:

// POST /capabilities/git/cloneCredential — signed
{
  "orgId": "org_…",
  "userId": "usr_…",
  "input": { "repo": "acme/api", "repos": ["acme/web"] }
}

orgId says whose installation to use. userId is present when a person is behind the call, and is the one to act as for a grant operation. input is the operation's own — see each capability's reference.

Answer with { "result": … }:

{ "result": { "scheme": "https-token", "username": "x-access-token", "token": "…", "expiresInSeconds": 3600 } }

Errors

Any non-2xx with a JSON body { "error": "…", "code": "…" }. The message is shown to the member. Two codes are kept apart all the way to the dashboard, because they ask the member for different things:

Our apps answer both with 409; the code is what counts. Anything else is reported as a failure of your app.

Timeouts and retries

Spunto waits 10 seconds for an answer. The call itself is never retried: one implementation answers, the result matters, and replaying a request blindly is how two of something get created. Where a capability does retry — runtime.create, when the app was unreachable or timed out — it says so, and the operation must be idempotent on the id it is given.

Long work (booting a machine, building an image) does not fit in 10 seconds and is not meant to: answer at once with a handle, and report progress through the status operation the capability defines.

Two addresses

Spunto calls your app on its base URL — which can be private, a name on an internal network. Browsers reach it on publicUrl. They are often the same; they don't have to be.

Publishing an app

What a review pins

The manifest is still read live, so a listed app can gain operations within the capabilities it was approved for, without anyone reviewing them again. Everything else stays as reviewed until a new version is approved:

To change any of them, Submit an update: the listed version stays in place while the new one is reviewed. To try a change before submitting it, register a second app — acme-git-staging — and keep the listed one for what was reviewed.

Rules for published apps

• Only the git and runtime capabilities are open to apps for now.
• Your pages live on your own origin: publicUrl is an absolute https URL, or left out to use the base URL.
• Spunto only calls public addresses, and doesn't follow redirects.
• Unlist takes a listed app off the marketplace: organizations using it lose it at once. Spunto may also suspend an app, which removes it from every organization and refuses every call to it.

Capabilities you can implement

The catalog of capabilities is the platform's and is closed: an app cannot invent one, since nothing would ever call it. Agent harnesses are apps too, but run inside the platform — the stream of a session is too hot a path to proxy — so they are not open to third parties.