APIs

The runtime exposes HTTP APIs for workspace management, app lifecycle control, session execution, and runtime configuration.

These APIs are used by the desktop app and by the surrounding platform services. They are not intended to be a generic public developer platform; they are the operational surface that keeps a workspace running.

Common endpoint families

Area	Typical endpoints	Purpose
Runtime config	/api/v1/runtime/config, /api/v1/runtime/status	Read and update runtime settings
Workspaces	/api/v1/workspaces	Create, list, update, delete, snapshot, and export workspaces
Agent runs	/api/v1/agent-runs, /api/v1/agent-runs/stream	Start a run and stream its events
App control	/api/v1/apps/:appId/start, /stop, /setup, /build-status, /ensure-running	Manage app lifecycle
App ports	/api/v1/apps/ports	Resolve the ports assigned to installed apps
Files	/api/v1/workspaces/:workspaceId/files/*	Read and write workspace files
Internal orchestration	/api/v1/internal/workspaces/:workspaceId/resolved-apps/start	Start all resolved apps for a workspace

Runtime config

/api/v1/runtime/config and /api/v1/runtime/status expose the runtime's own configuration and health-related state.

Use these endpoints when you need to:

• inspect the current model/provider setup
• verify the runtime is healthy
• update runtime-level settings

Workspace APIs

The workspace endpoints manage the durable workspace shape:

• create a workspace
• list available workspaces
• fetch a workspace by id
• update workspace metadata
• delete a workspace
• apply a template
• clone a template from a URL
• read and write workspace files
• export or snapshot a workspace

This is the main API family behind workspace materialization and workspace editing flows.

Agent runs

The agent-run endpoints are the execution surface:

• POST /api/v1/agent-runs starts a run
• POST /api/v1/agent-runs/stream starts a run and streams events back

These endpoints are what the runtime uses when it needs turn-level execution and event streaming.

App lifecycle

Apps are controlled through lifecycle endpoints such as:

• start
• stop
• setup
• ensure-running
• build-status

App lifecycle is driven by the app manifest. The runtime reads app.runtime.yaml, resolves the declared commands, and then starts or stops the app accordingly.

For public documentation, the key idea is simple: the runtime only needs the manifest contract. It does not care what implementation framework the app uses internally.

App port resolution

GET /api/v1/apps/ports resolves the actual runtime-assigned ports for installed apps.

That matters because app ports are not always fixed. The runtime may assign them dynamically based on workspace state and app position.

Authentication and trust

These APIs are operational, so access is controlled by the surrounding platform. In the normal product flow:

• the desktop calls the runtime directly in local/standalone contexts
• the platform calls the runtime through authenticated service layers
• the runtime uses its own service contracts rather than exposing raw workspace internals to browsers

Practical takeaway

If you are building against the runtime, think in three categories:

1. workspace APIs for durable workspace state
2. agent-run APIs for execution
3. app lifecycle APIs for app-specific behavior

That separation keeps the public model simple even though the runtime itself manages a lot of state.