Skip to main content
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:
FieldTypeRequiredDescription
commandstringYesShell command to execute
cwdstringNoWorking directory for command execution
timeoutintegerNoTimeout 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us