Runtimes
A runtime is an execution environment where agents run tools that interact with files, execute code, or perform shell operations. Runtimes provide sandboxed access to computing resources -- your own servers, cloud sandboxes, or directories on your local machine.
Agents never see or manage runtimes. When an agent calls a tool, it gets back a result. Whether that tool ran on a remote server, inside a cloud sandbox, or on your laptop is entirely managed by the platform. Runtimes are configured by the person building the workflow, not by the agent at execution time.
Each runtime has a name and an optional description that appears on its card tile in the settings page, helping you distinguish runtimes at a glance.
Runtime Providers
ORQO supports three runtime providers, each suited for different use cases.
SSH
Connect any server or virtual machine you control. SSH runtimes work with any Linux or macOS machine reachable via SSH -- cloud VMs, on-premise servers, development boxes.
| Field | Required | Description |
|---|---|---|
| Host | Yes | IP address or hostname of the server |
| Port | No | SSH port (default: 22) |
| Username | Yes | SSH login username |
| SSH Key | Yes | Private key credential for authentication |
SSH runtimes are created manually in Settings > Runtimes. You provide the connection details and an SSH key credential. ORQO uses the key to authenticate when it needs to execute a command on the server.
Daytona
Cloud-hosted sandboxed environments powered by Daytona. Daytona runtimes are fully managed -- ORQO can create, start, stop, and destroy them automatically.
| Field | Required | Description |
|---|---|---|
| Sandbox ID | Yes | Daytona sandbox identifier |
| API Key | Yes | Daytona API credential |
Daytona runtimes are useful when you need disposable, isolated environments for code execution and don't want to maintain your own infrastructure.
Desktop App
Local directories exposed through the ORQO Desktop App. Desktop App runtimes connect your local machine to ORQO -- agents can read files, write files, and run commands directly in your local directories.
Desktop App runtimes are not created manually. When the ORQO Desktop App connects and registers workspaces, runtimes appear automatically in your ORQO dashboard. When the app disconnects, the runtimes go offline.
| Behavior | Details |
|---|---|
| Created by | ORQO Desktop App (automatic) |
| Connection | WebSocket relay (outbound from your machine -- no firewall config needed) |
| Scope | Each workspace directory becomes its own runtime |
| State tracking | Running when app is connected, stopped when disconnected |
This is the fastest way to give agents access to local files -- install the ORQO Desktop App, add a workspace, and it appears as a runtime in ORQO.
Runtime States
Every runtime has a state that reflects its current availability:
| State | Meaning |
|---|---|
| Running | Connected and available for tool execution |
| Stopped | Not currently active -- can be started or will come online when the desktop app reconnects |
| Pending | Being provisioned (Daytona) |
| Creating | Infrastructure is being set up (Daytona) |
| Archived | No longer in use but preserved for reference |
| Error | Something is wrong -- check the error message for details |
Assigning Runtimes
Runtimes reach agents through two paths:
1. Skills
Link a runtime to a Skill. Any agent with that skill assigned can execute tools in the runtime during any stage.
This is the right approach when a runtime is fundamental to the agent's capabilities. For example, a "Local Codebase" skill that bundles file tools with a Desktop App runtime pointing to your project directory.
2. Stage Assignments
Assign a runtime to a specific Stage. All agents participating in that stage can use the runtime, but only during that stage's execution.
This is the right approach when a runtime is needed for a specific task. For example, a "Deploy" stage that needs SSH access to a production server, while other stages don't.
When a stage has Auto Manage Runtime enabled, ORQO automatically starts the runtime when the stage begins and stops it when the stage ends. This is useful for Daytona runtimes to avoid unnecessary uptime.
Health Checks
ORQO periodically checks whether runtimes are reachable:
| Provider | Health check method |
|---|---|
| SSH | Opens an SSH connection using stored credentials |
| Daytona | Queries the Daytona API for sandbox state |
| Desktop App | Checks when the app was last seen via the relay |
If a health check fails, the runtime transitions to the error state with a diagnostic message.
Security
Runtimes are scoped to your organization. Only workflows running within your organization can execute commands on your runtimes. The platform routes commands based on the runtime assignment in the workflow configuration -- agents cannot target arbitrary runtimes.
For Desktop App runtimes, security is enforced at multiple levels:
- Workspace boundaries -- The app only exposes directories you explicitly declare. Path traversal outside workspace roots is blocked.
- API token authentication -- The app authenticates with ORQO using an organization-scoped API token.
- TLS encryption -- All communication between the app and ORQO uses WSS (WebSocket over TLS).
- Operation confirmation -- The app can optionally prompt before allowing write operations or shell commands.
See Set Up the ORQO Desktop App for setup instructions.
- Set Up the ORQO Desktop App to connect local directories
- Create a Skill to bundle a runtime with tools
- Add Stages to assign a runtime to a stage