From a build to a link in six steps.

Sign up with your invite (no invite yet? join the waitlist), then create a key from your account. It starts sb_, is shown once, and belongs to your organisation. Keep it in an environment variable, not in the repo.

$ export SIMBASE_KEY=sb_…$ curl -s https://api.simbase.dev/v1/me -H "Authorization: Bearer $SIMBASE_KEY"

The MCP server is streamable HTTP at https://api.simbase.dev/mcp, with the same bearer key.

Claude Code

$ claude mcp add --transport http simbase https://api.simbase.dev/mcp --header "Authorization: Bearer sb_…"

Cursor

Add to ~/.cursor/mcp.json, or .cursor/mcp.json in the repo if everyone on the project should have it (then use an env var, not the literal key):

{
  "mcpServers": {
    "simbase": {
      "url": "https://api.simbase.dev/mcp",
      "headers": { "Authorization": "Bearer sb_…" }
    }
  }
}

Anything else

Any client that supports a remote MCP server with a custom header works: URL https://api.simbase.dev/mcp, header Authorization: Bearer sb_…. If your client supports MCP sign-in (OAuth), you can leave the header off and sign in through the browser instead. No MCP at all? Everything below is plain HTTP.

Simbase runs what you built; it never sees your source. For iOS that’s a simulator build — an .ipa is signed for hardware and won’t install. Zip the .app with ditto, which keeps the executable bit that plain zip in some CI setups drops.

iOS

$ xcodebuild -scheme App -sdk iphonesimulator -configuration Debug \  -derivedDataPath build build$ ditto -c -k --keepParent build/Build/Products/Debug-iphonesimulator/App.app App.zip $ curl -s https://api.simbase.dev/v1/artifacts \  -H "Authorization: Bearer $SIMBASE_KEY" \  -H "content-type: application/octet-stream" \  -H "x-filename: App.zip" \  --data-binary @App.zip

Android

$ ./gradlew assembleDebug $ curl -s https://api.simbase.dev/v1/artifacts \  -H "Authorization: Bearer $SIMBASE_KEY" \  -H "content-type: application/octet-stream" \  -H "x-filename: app-debug.apk" \  --data-binary @app/build/outputs/apk/debug/app-debug.apk

Either way you get an artifact back. Its id is what a run refers to:

{
  "artifactId": "art_8Kq2…",
  "sha256": "4f1c…e07a",
  "bytes": 38211042,
  "filename": "App.zip",
  "platform": "ios"
}

Already have the build at an HTTPS URL, say a CI artifact? Skip the upload and pass app.url instead. The fetch is HTTPS-only and refuses private, loopback and link-local addresses, including on redirects.

Through MCP, ask your agent in plain words. It calls run_device_test, which takes the same fields as the REST request below.

“Build the app for the simulator and upload it to Simbase. Then on an iPhone 17 Pro: open Settings, turn on Beta features, and screenshot it as beta-on. Put the evidence link in the PR description.”

Over HTTP:

$ curl -s https://api.simbase.dev/v1/runs \  -H "Authorization: Bearer $SIMBASE_KEY" \  -H "content-type: application/json" \  -d '{    "app": { "artifactId": "art_8Kq2…" },    "device": { "platform": "ios", "name": "iPhone 17 Pro" },    "label": "settings: beta toggle",    "screenshots": ["beta-on"],    "steps": [      { "action": "tap", "id": "tab_settings" },      { "action": "wait_for", "label": "Settings" },      { "action": "tap", "id": "beta_toggle" },      { "action": "screenshot", "name": "beta-on" }    ]  }'

The response is { run } with status: "pending" and a queuePosition. Explicit steps are the only way to describe a hosted run — a plain-English scenario is refused with invalid_request. Your agent writes the steps; it knows the app, it just changed it.

Long-poll until the run is finished. Each call holds for up to timeoutMs (at most 60 seconds) and returns the run either way; call again if it isn’t terminal yet.

$ curl -s "https://api.simbase.dev/v1/runs/$RUN_ID/wait?timeoutMs=60000" \  -H "Authorization: Bearer $SIMBASE_KEY"

Statuses move pending → preparing → running, then end in one of five:

A finished run carries an evidenceUrl: a page with the verdict, the named screenshots, the executed steps, the recording and the timings. It’s private to your organisation by default; who can open it is up to you. The same data is in the JSON:

{
  "id": "run_5TzQ…",
  "status": "passed",
  "device": { "name": "iPhone 17 Pro", "runtime": "26.3", "platform": "ios" },
  "verdict": { "pass": true, "summary": "The Beta features toggle reads On." },
  "screenshots": [
    { "name": "beta-on", "url": "https://api.simbase.dev/e/q7Hc2vX9mTzR/shot-beta-on.png" }
  ],
  "video": { "gifUrl": "…/preview.gif", "mp4Url": "…/video.mp4" },
  "evidenceUrl": "https://api.simbase.dev/e/q7Hc2vX9mTzR",
  "executedSteps": [ … ],
  "timings": { "queueMs": 400, "installMs": 3100, "stepsMs": 7200, "occupancyMs": 15300 }
}

The PR comment links to it. Screenshots don’t render inline there unless the run is public, because GitHub fetches images without signing in. Evidence lasts 7 days on Free and up to 180 on paid plans.

executedSteps is exactly what ran. Save it in the repo and submit it again after the next change — same build, same steps, same screens.

The body of POST /v1/runs and the arguments of run_device_test. Only app is required.

Each step is an object with an action. Elements are found by accessibility id, label or value, or by coordinates.

Base URL https://api.simbase.dev. Every /v1 route and /mcp takes Authorization: Bearer sb_…. Runs and artifacts belong to your organisation; anything else is a 404, never a 403.

Evidence files a run can have: shot-<name>.png, video.mp4, preview.gif, report.md, app.log, build.log, ui.json.

In CI you don’t need a stored key. A GitHub Actions job asks GitHub for an OIDC token, which says which repo, ref and workflow it came from, and exchanges it for a Simbase CI token that lasts an hour. There’s no secret to store, leak or rotate.

An owner of your organisation trusts each repo in /app/settings/access, which also shows your organisation id. The workflow needs permissions: id-token: write so GitHub will mint the token.

The short version: the composite action

packages/access/action does the exchange, uploads the build, runs the steps, waits, and comments the verdict and the evidence link on the pull request.

permissions:
  id-token: write
  contents: read
  pull-requests: write

jobs:
  device-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/build-simulator-app.sh build/MyApp.zip
      - uses: nickbabenko/simbase/packages/access/action@main
        with:
          simbase-url: https://api.simbase.dev
          org: ${{ vars.SIMBASE_ORG }}
          build: build/MyApp.zip
          steps-file: .simbase/smoke.json

The exchange, by hand

Ask GitHub for an ID token with the audience set to exactly https://api.simbase.dev, then post it with your organisation id:

POST https://api.simbase.dev/oidc/github/token
content-type: application/json

{
  "token": "<Actions ID token, requested with audience = https://api.simbase.dev>",
  "org": "<your org id>"
}

You get a bearer token scoped to runs, for one hour:

{
  "access_token": "sbci_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "runs:read runs:write",
  "org_id": "org_…",
  "repo": "your-org/your-repo"
}

As a workflow step:

- name: Get a Simbase token
  env:
    SIMBASE_ORG: ${{ vars.SIMBASE_ORG }}
  run: |
    ID_TOKEN=$(curl -sfS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://api.simbase.dev" | jq -r .value)
    TOKEN=$(curl -sfS -X POST https://api.simbase.dev/oidc/github/token \
      -H "content-type: application/json" \
      -d "$(jq -n --arg token "$ID_TOKEN" --arg org "$SIMBASE_ORG" '{token: $token, org: $org}')" \
      | jq -r .access_token)
    echo "::add-mask::$TOKEN"
    echo "SIMBASE_KEY=$TOKEN" >> "$GITHUB_ENV"

Later steps use $SIMBASE_KEY exactly like a key. It expires on its own, and removing the repo’s trust revokes it.

Every non-2xx response has the same shape. code is for your program; message is for you. Limit errors say which limit, how much you’ve used, and when to retry.

{
  "error": {
    "code": "quota_exceeded",
    "message": "60 device-minutes used in the last 24 hours.",
    "limit": 60,
    "current": 60,
    "retryAfterSeconds": 3480
  }
}

Per organisation, by plan. The same numbers the API enforces.

Hit one sooner than you expected? Tell us — the numbers are set for a small fleet, not carved in stone.