Workload Runtime

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Workloads that include an interface_config block become consumer-facing workload runtime interfaces. Orqestra lists them on the Apps page, exposes them as embeddable widgets, and routes execution through the same governed trigger system that backs every other consumer interface.

What Is Workload Runtime?

A runtime workload is a workload with a configured interface_config. The configuration tells the portal how to render input fields, what presentation mode to use, how to display output, and how to theme the surface.

Three presentation modes are available:

Runtime workloads appear on the Apps page at /workload-runtime and can be shared with internal or external users via share links.

Minimal interface_config

{
  "presentation_mode": "form",
  "description": "Classify a support ticket and route it to the right queue.",
  "input_fields": [
    { "name": "ticket_body", "label": "Ticket text", "type": "textarea", "required": true }
  ],
  "output_display": "text"
}

Attach interface_config when creating or updating a workload:

curl -X PATCH http://localhost:8000/v1/workloads/{workload_id} \
  -H "Content-Type: application/json" \
  -d '{
    "interface_config": {
      "presentation_mode": "form",
      "description": "Classify a support ticket.",
      "input_fields": [
        { "name": "ticket_body", "label": "Ticket text", "type": "textarea", "required": true }
      ],
      "output_display": "text"
    }
  }'

Apps (/workload-runtime)

The Apps page at /workload-runtime shows a card grid of every published workload the current principal can access. Each card shows the workload name, description, presentation mode badge, and last-updated timestamp.

Filtering and Search

Clicking a card opens the workload runtime at /workload-runtime/[slug].

Workload Runtime (/workload-runtime/[slug])

The runtime page loads the active release for the workload identified by slug and renders the presentation mode declared in interface_config.

Form Mode

Form mode generates input controls directly from interface_config.input_fields. Supported field types:

Each field entry supports:

{
  "name": "priority",
  "label": "Priority",
  "type": "select",
  "required": true,
  "options": ["low", "medium", "high"],
  "default": "medium"
}

Submitting the form calls the workload trigger endpoint, which executes the governed flow and streams output back to the runtime page.

Output Display

The output_display field controls how the execution result is rendered:

Runtime Data Flow

Embed Mode (/[slug])

Embed mode renders the same workload runtime with no sidebar, navigation header, or portal chrome. It is designed for iframe embedding in external portals, dashboards, or documentation sites. Only allow-listed slugs render: ticket-classifier plus any listed in ORQESTRA_EMBED_ROOT_SLUGS. Any other top-level path returns a 404, and keeps frame-ancestors 'none'.

<iframe
  src="https://orqestra.example.com/ticket-classifier"
  width="800"
  height="600"
  style="border: none;"
></iframe>

Embed mode accepts a token query parameter for link-shared access:

<iframe
  src="https://orqestra.example.com/ticket-classifier?token=slk_abc123"
  width="800"
  height="600"
></iframe>

The token is validated server-side against the share link record. Expired or revoked tokens receive a 401 response and the embed shows a permission error state.

Custom Theming

Each workload interface can define a theme block inside interface_config to override the portal design system:

{
  "presentation_mode": "form",
  "theme": {
    "accent_color": "#6366f1",
    "background_color": "#0f172a",
    "font_family": "Inter, sans-serif",
    "border_radius": "8px"
  }
}

Theme properties are applied as CSS variables at the workload runtime root element:

Unset properties fall through to the portal design system defaults. You do not need to specify every property — partial theme objects are valid.

Share Links

Share links grant access to a workload runtime interface without requiring a full portal account. Newly-created links are time-limited and single-use by default.

Access Modes

Create a Share Link

curl -X POST http://localhost:8000/v1/workloads/{workload_id}/share-links \
  -H "Content-Type: application/json" \
  -d '{
    "ttl_hours": 24,
    "max_uses": 1
  }'

Response (201 Created):

{
  "share_link_id": "11111111-1111-1111-1111-111111111111",
  "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "token": "<share-link-token>",
  "label": null,
  "max_uses": 1,
  "use_count": 0,
  "expires_at": "2026-04-18T12:00:00Z",
  "revoked": false,
  "created_at": "2026-04-11T12:00:00Z",
  "created_by": "user:alice"
}

The token value is appended to the embed or workload runtime URL as ?token=<token>.

List Share Links

curl http://localhost:8000/v1/workloads/{workload_id}/share-links

Revoke a Share Link

curl -X DELETE http://localhost:8000/v1/workloads/{workload_id}/share-links/{link_id}

Revocation takes effect immediately. Active sessions using the token receive 401 on their next request.

Workload Interface Editor

The Interface tab on the workload detail page (/workloads/{id}) provides a visual editor for interface_config. No direct API calls are needed for common configuration tasks.

Changes in the editor are saved to interface_config on the workload record. They take effect on the next page load; no release cycle is required for UI configuration changes.

Release governance applies to the flow the workload executes, not the interface_config shell. You can update labels, theme colors, and field descriptions without creating a new release.

SDK

from orqestra_sdk import OrqestraClient
 
async with OrqestraClient(base_url="http://localhost:8000", api_key="...") as client:
    # List all accessible runtime workloads
    workloads = await client.workload_runtime.list()
    for workload in workloads:
        print(workload.slug, workload.presentation_mode)
 
    # Get a specific runtime workload by slug
    workload = await client.workload_runtime.get("ticket-classifier")
    print(workload.interface_config.input_fields)
 
    # Execute a runtime workload
    result = await client.workload_runtime.execute(
        slug="ticket-classifier",
        inputs={"ticket_body": "Login page is broken for EU users."},
        environment="production",
    )
    print(result["result"])
 
    # Create a share link
    link = await client.workload_runtime.create_share_link(
        workload_id="a1b2c3d4-0000-0000-0000-000000000001",
        ttl_hours=24,
        max_uses=1,
    )
    print(link["token"])
 
    # List share links
    links = await client.workload_runtime.list_share_links(workload_id="a1b2c3d4-0000-0000-0000-000000000001")
 
    # Revoke a share link
    await client.workload_runtime.revoke_share_link(
        workload_id="a1b2c3d4-0000-0000-0000-000000000001",
        share_link_id="slk_abc123def456",
    )

CLI

Run a workload:

orqestractl workload run ticket-classifier \
  --environment production \
  --input ticket_body="Login page is broken for EU users."

workload run waits up to 600 seconds by default so longer agent and retrieval flows can finish. Use --timeout <seconds> when a workload has a tighter or longer operator SLA.

Internal service credentials can execute on behalf of an explicitly bound subject actor. The subject actor must already have a workload principal binding; non-internal callers cannot set these fields:

orqestractl workload run sample-review \
  --environment dev \
  --subject-execution-mode interactive \
  --subject-actor-ref user:ops@orqestra.dev \
  --subject-actor-type user \
  --subject-actor-auth-mode programmatic \
  --input operation=model_json

Run with multiple inputs and JSON output:

orqestractl workload run report-generator \
  --environment dev \
  --input quarter=Q1 \
  --input region=EMEA \
  --format json

Manage share links:

# Create a single-use link valid for 24 hours
orqestractl workload share create ticket-classifier \
  --ttl 24 \
  --max-uses 1
 
# List all share links for a workload
orqestractl workload share list ticket-classifier
 
# Revoke a link
orqestractl workload share revoke ticket-classifier slk_abc123def456

API Reference

List Apps Entries

curl http://localhost:8000/v1/workloads/runtime-enabled

Query parameters:

Response (200 OK):

[
  {
    "slug": "ticket-classifier",
    "name": "Ticket Classifier",
    "description": "Classify a support ticket and route it.",
    "presentation_mode": "form",
    "owner_ref": "team:support",
    "updated_at": "2026-04-10T09:00:00Z"
  }
]

Get Runtime Workload by Slug

curl http://localhost:8000/v1/workloads/by-slug/{slug}

Response (200 OK):

{
  "slug": "ticket-classifier",
  "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "name": "Ticket Classifier",
  "interface_config": {
    "presentation_mode": "form",
    "description": "Classify a support ticket and route it.",
    "input_fields": [
      { "name": "ticket_body", "label": "Ticket text", "type": "textarea", "required": true }
    ],
    "output_display": "text",
    "theme": {}
  }
}

Execute Runtime Workload

curl -X POST http://localhost:8000/v1/workloads/by-slug/{slug}/execute \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "inputs": {
      "ticket_body": "Login page is broken for EU users."
    }
  }'

Response (200 OK, streaming):

{
  "execution_id": "ex1a2b3c-0000-0000-0000-000000000001",
  "status": "completed",
  "output": "Priority: high\nQueue: infrastructure",
  "started_at": "2026-04-11T12:00:00Z",
  "completed_at": "2026-04-11T12:00:01Z"
}

Pass a token query parameter when executing via a link-shared share link:

curl -X POST "http://localhost:8000/v1/workloads/by-slug/{slug}/execute?token=<share-link-token>" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"ticket_body": "Login broken."}}'

Sync vs. Async

By default, execute is sync: the request blocks until the run reaches a terminal state and returns its stored result as 200. If the run finishes but its result hasn’t been persisted yet, or the dispatch wait budget runs out first, the response falls back to 202 Accepted (below) instead of a 200 with a missing result.

A caller can instead opt into async dispatch, per request, with the Prefer: respond-async header (or the ?mode=async query parameter):

curl -X POST "http://localhost:8000/v1/workloads/by-slug/{slug}/execute" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"inputs": {"ticket_body": "Login page is broken for EU users."}}'

An async request enqueues the run and returns 202 Accepted immediately, without waiting at all. Async dispatch requires the deployment to run queued dispatch; against an inline-dispatch deployment it is refused with 409 async_dispatch_unavailable.

Queued Execution

When the runtime cannot reach a terminal state within its wait budget (sync), or immediately (async), it returns 202 Accepted with {"execution_id": ..., "state": "queued"} instead of a completed result. Poll GET /v1/executions/{execution_id} for status — both the sync wait-budget fallback and every async request are read back the same way. Once the run finishes, the original submitter only — within the deployment’s short retention window (30 days by default) — can read the output from the response’s queued_result field:

{
  "outcome": "success",
  "queued_result": {
    "result": { "priority": "high", "queue": "infrastructure" },
    "result_at": "2026-04-11T12:00:03Z"
  }
}

Another member of the same workspace, or the same submitter after the retention window has passed, sees queued_result: null. A caller outside the tenant is refused the execution outright, not shown a null field. orqestractl run and orqestractl workload run make one follow-up status read after a queued submit and render the result if it has landed by then; otherwise read it later with orqestractl execution get <execution_id>. See CLI above.

Share Link Endpoints

Code Mode Through The Control Plane

orqestra execute code-mode and the SDK’s code_mode run an agent-authored script through the runtime gateway’s mediated-RPC executor, but the call goes through the control plane, not directly to the runtime gateway. The control plane authorizes the caller against workspace_id, resolves the workload, active release, and execution subject itself, and forwards a control-plane-constructed request to the runtime gateway — the caller never supplies actor, tenant, principal, delegation, or execution-mode fields, and any such field in the request body is rejected with 422.

SDK:

result = await client.workload_runtime.code_mode(
    workspace_id=workspace_id,
    workload_slug="ticket-triage",
    code="result = tools.classify(ticket_body=inputs['ticket_body'])",
    language="python",
    environment="production",
)
print(result["execution_id"])

CLI:

orqestra execute code-mode \
  --workspace-id "$WORKSPACE_ID" \
  --workload-slug ticket-triage \
  --code "result = tools.classify(ticket_body=inputs['ticket_body'])"

The response carries the control-plane-assigned execution_id, committed to a durable governance audit row before the runtime gateway is called; there is no retry, so an ambiguous transport error is returned as a typed 502/504 with that execution_id rather than shown as success. The same client also exposes read-only proxies for runtime-gateway metadata, each scoped by workspace_id: runtime_plugins, runtime_system_meta, and runtime_mcp_manifest. runtime_mcp_call invokes one of the built-in tools (execute_flow, query_knowledge_base, inspect_evidence): the control plane authorizes it, persists one invocation row, and the runtime gateway calls back under a one-use ticket. The response is {status, result} with status one of success, queued (dispatched, not yet terminal) or failed (an execute_flow that ended with a non-success outcome, with its execution_id). A lost or malformed response is a typed 502/503, recorded as an unknown invocation that is never retried.

Best Practices

Use interface_config only for UI concerns. Governance, policy evaluation, and flow logic belong in the release and flow assets, not in interface_config.

Prefer link_shared over public for external sharing. public mode is rate-limited and intended for low-sensitivity demos only.

Keep share links short-lived. The default is a 24-hour, single-use bearer token. Raise max_uses only for planned distribution and stay within the API cap.

Theme conservatively. Large contrast differences from portal defaults can break accessibility guarantees. Use the theme picker in the Workload Interface Editor to preview before publishing.