Create a remote-backed run (caller executes the agent)

Create a run whose agent process runs on the caller's host (CLI, GitHub Action, self-hosted runner) instead of inside a platform container. Returns ephemeral HMAC-signed sink credentials the caller plugs into HttpSink to stream RunEvents back via POST /api/runs/{runId}/events. The secret is returned exactly once and is never retrievable afterwards. Status lifecycle (pending → running → terminal) flows through the signed-event ingestion routes. Matches the quota/rate-limit gates of classic runs: per_org_global_rate_per_min and max_concurrent_per_org both apply.

A remote runner addresses one connection per integration (its api_call tool carries no connection argument), so a run whose connection cascade binds several connections to an integration is refused with 409 missing_integration_connection carrying one remote_binds_one_connection item per such integration (field: integrations.<id>): pick one with a member pin (a set an admin pin or an enforced org default imposes is narrowed by an admin), or run the agent on the platform.

Permission: agents:run; an inline source (a manifest the body carries) also requires agents:write. Caller-authored inline manifests require the read permission for each dependency type. Existing dependencies must be readable in an accessible source space (API keys remain pinned to their space), or belong to the readable system/catalog sources. Missing read permissions return 403; inaccessible existing sources return 404, before readiness checks or creation of a run. Nonexistent dependencies retain the normal validation errors.

POST/api/runs/remote

Authorization

better-auth.session_token<token>

Cookie session from Better Auth. Requires X-Org-Id header for org-scoped routes.

In: cookie

Header Parameters

X-Org-Id?string

Organization ID. Required for cookie auth. Not needed for API key auth (org resolved from key).

Formatuuid

Appstrate-Version?string

API version override (format: YYYY-MM-DD). Defaults to the org's pinned version or the current platform version.

Idempotency-Key?string

Unique key for idempotent requests (max 255 chars). Prevents duplicate resource creation on retries. Cached for 24 hours, scoped to the organization and space: a repeat with the same method, URL and body replays the original response with Idempotent-Replayed: true, the same key with a different method, URL or body is 422 idempotency_conflict, and a concurrent duplicate is 409 idempotency_in_progress. Current permissions are checked again; run responses are projected using current visibility. This operation honours the header because it declares this parameter — operations that do not declare it refuse the header with 400 idempotency_not_supported rather than silently ignoring it (see the “Idempotency” section of the API description).

Lengthlength <= 255

Request Body

application/json

source*|

Two attribution shapes: inline ships the manifest+prompt in the body (ad-hoc agents — always lands on a shadow ephemeral package); registry declares the package by id and the server reads the manifest from its own catalog (deterministic attribution, no fingerprint reconciliation).

spaceId*string

Length1 <= length

input?object

Run input, validated against the agent's input schema. File fields (format: uri + contentMediaType) accept ONLY inline data:<mime>;name=<file>;base64,<payload> URIs on remote runs — upload:// and appfile:// references are rejected (400), because the run executes on the caller's host, whose workspace the platform never provisions.

dependency_overrides?

Per-run dependency version overrides (#666/#686). Flat map { "@scope/dep": "draft" | "<semver|dist-tag>" }; keys may name a declared skill OR integration. "draft" opts that dependency into its working copy and needs WRITE authority on THAT dependency — 403 draft_not_writable naming it otherwise, since running an unpublished definition answers to its author whichever package declared it. Any other value replaces the manifest pin; an unsatisfiable pin aborts the run with dependency_unresolved (422). A key that names no declared skill or integration of the effective manifest is a 400 naming the key, and it is raised BEFORE the authority gate — a typo is a malformed request, not a missing grant.

contextSnapshot?object

Caller-provided execution-environment metadata (os, cli version, git sha). Capped at 16 KiB serialised.

sink?

curl -X POST "https://your-instance/api/runs/remote" \  -H "Content-Type: application/json" \  -d '{    "source": {      "kind": "inline",      "manifest": {},      "prompt": "string"    },    "spaceId": "string"  }'

{
  "id": "string",
  "url": "http://example.com",
  "finalize_url": "http://example.com",
  "secret": "string",
  "expiresAt": "2019-08-24T14:15:22Z"
}

{
  "type": "https://docs.appstrate.dev/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "name: Invalid input: expected string, received undefined (+2 more)",
  "code": "validation_failed",
  "request_id": "req_abc123",
  "errors": [
    {
      "field": "name",
      "code": "required",
      "message": "Invalid input: expected string, received undefined"
    },
    {
      "field": "email",
      "code": "invalid_format",
      "message": "Invalid email address"
    },
    {
      "field": "age",
      "code": "invalid_type",
      "message": "Invalid input: expected number, received string"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing session",
  "code": "unauthorized",
  "request_id": "req_abc123"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions",
  "code": "forbidden",
  "request_id": "req_abc123"
}

{
  "type": "https://docs.appstrate.dev/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Resource not found",
  "code": "not_found",
  "request_id": "req_abc123"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/rate-limited",
  "title": "Rate Limited",
  "status": 429,
  "detail": "Too many requests. Please try again shortly.",
  "code": "rate_limited",
  "request_id": "req_abc123",
  "retry_after": 30
}

{
  "type": "https://docs.appstrate.dev/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again or contact support.",
  "code": "internal_error",
  "request_id": "req_abc123"
}

Create a remote-backed run (caller executes the agent)

Authorization

Header Parameters

Request Body

Multiple body fields failed validation

Single non-body field failed validation