Process API

Execute commands and manage processes in Daytona sandboxes

The Process API provides endpoints for executing commands, managing pseudo-terminal (PTY) sessions, shell sessions, and interpreter contexts within Daytona sandboxes.

Command Execution

Execute Command

Execute a shell command synchronously and return the output.

POST /process/execute

Request Body:

{
  "command": "ls -la",
  "cwd": "/workspace",
  "timeout": 30
}

Parameters:

Field	Type	Required	Description
command	string	Yes	Shell command to execute
cwd	string	No	Working directory for command execution
timeout	integer	No	Timeout in seconds (default: 10)

Response:

{
  "result": "total 24\ndrwxr-xr-x  5 user user 4096 ...",
  "exitCode": 0
}

PTY Sessions

Pseudo-terminal (PTY) sessions provide interactive terminal access with WebSocket support.

Create PTY Session

Create a new PTY session for interactive terminal access.

POST /process/pty

Request Body:

{
  "id": "my-terminal",
  "cwd": "/workspace",
  "rows": 24,
  "cols": 80,
  "envs": {
    "TERM": "xterm-256color"
  },
  "lazyStart": false
}

Response:

{
  "sessionId": "my-terminal"
}

List PTY Sessions

Get all active PTY sessions.

GET /process/pty

Response:

{
  "sessions": [
    {
      "id": "my-terminal",
      "active": true,
      "rows": 24,
      "cols": 80,
      "cwd": "/workspace",
      "envs": {},
      "lazyStart": false,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Get PTY Session

Get information about a specific PTY session.

GET /process/pty/{sessionId}

Connect to PTY Session

Establish a WebSocket connection for interactive terminal access.

GET /process/pty/{sessionId}/connect
Upgrade: websocket

Resize PTY Session

Change the terminal dimensions.

POST /process/pty/{sessionId}/resize

Request Body:

{
  "rows": 30,
  "cols": 120
}

Parameters:

• rows: Terminal height (1-1000)
• cols: Terminal width (1-1000)

Delete PTY Session

Terminate and delete a PTY session.

DELETE /process/pty/{sessionId}

Shell Sessions

Shell sessions allow executing multiple commands within the same session context.

Create Session

Create a new shell session.

POST /process/session

Request Body:

{
  "sessionId": "build-session"
}

List Sessions

Get all active shell sessions.

GET /process/session

Response:

[
  {
    "sessionId": "build-session",
    "commands": [
      {
        "id": "cmd-1",
        "command": "npm install",
        "exitCode": 0
      }
    ]
  }
]

Get Session

Get details of a specific session.

GET /process/session/{sessionId}

Execute in Session

Execute a command within an existing session.

POST /process/session/{sessionId}/exec

Request Body:

{
  "command": "npm run build",
  "async": false,
  "runAsync": false,
  "suppressInputEcho": false
}

Response:

{
  "cmdId": "cmd-2",
  "exitCode": 0,
  "stdout": "Build completed successfully",
  "stderr": "",
  "output": "Build completed successfully"
}

Get Session Command

Get details of a specific command in a session.

GET /process/session/{sessionId}/command/{commandId}

Get Command Logs

Get logs for a specific command. Supports WebSocket streaming.

GET /process/session/{sessionId}/command/{commandId}/logs?follow=true

Query Parameters:

• follow: Stream logs in real-time via WebSocket (boolean)

Send Input to Command

Send input to a running interactive command.

POST /process/session/{sessionId}/command/{commandId}/input

Request Body:

{
  "data": "yes\n"
}

Delete Session

Delete a shell session.

DELETE /process/session/{sessionId}

Interpreter Contexts

Manage isolated code interpreter contexts for executing code.

Create Interpreter Context

Create a new isolated interpreter context.

POST /process/interpreter/context

Request Body:

{
  "cwd": "/workspace",
  "language": "python"
}

Response:

{
  "id": "ctx-abc123",
  "active": true,
  "cwd": "/workspace",
  "language": "python",
  "createdAt": "2024-01-15T10:30:00Z"
}

List Interpreter Contexts

Get all user-created interpreter contexts.

GET /process/interpreter/context

Execute Code

Execute code in an interpreter context via WebSocket.

GET /process/interpreter/execute
Upgrade: websocket

Delete Interpreter Context

Delete an interpreter context.

DELETE /process/interpreter/context/{id}

Best Practices

Use PTY sessions for interactive terminal access and shell sessions for programmatic command execution with session state.

• Set appropriate timeouts for long-running commands
• Clean up sessions when no longer needed
• Use WebSocket connections for real-time output streaming
• Handle exit codes to detect command failures
• Specify working directory to ensure commands run in correct context

Example Usage

import { ToolboxApiClient } from '@daytona/toolbox-api-client'

const client = new ToolboxApiClient({
  baseURL: 'http://localhost:8080',
  headers: { Authorization: `Bearer ${token}` }
})

// Execute a command
const result = await client.process.executeCommand({
  command: 'git status',
  cwd: '/workspace',
  timeout: 30
})

console.log(result.data.result)

Prefer using the official Daytona SDKs over direct API calls for better type safety and error handling.