Process Execution

Execute code and commands in Daytona sandboxes

The Process API provides powerful capabilities for executing code and running shell commands within a sandbox environment.

Overview

Daytona supports two primary execution modes:

• Code execution - Run code directly using language-specific runtimes
• Command execution - Execute shell commands with full control over the environment

Both modes support synchronous and asynchronous execution, with comprehensive output handling.

Code Execution

Basic Code Running

Execute code in the sandbox using the appropriate language runtime:

const response = await sandbox.process.codeRun(`
  const x = 10;
  const y = 20;
  console.log(\`Sum: \${x + y}\`);
`);

console.log(response.artifacts.stdout); // Output: Sum: 30
console.log(response.exitCode); // 0 for success

Code Execution with Parameters

Pass environment variables and command-line arguments:

const response = await sandbox.process.codeRun(
  `
  console.log(process.env.MY_VAR);
  console.log(process.argv);
  `,
  {
    env: { MY_VAR: 'Hello World' },
    argv: ['arg1', 'arg2']
  },
  30 // timeout in seconds
);

code · string · required

Code to execute in the sandbox

params · CodeRunParams

Execution parameters

Show properties

argv · string[]

Command line arguments

env · Record<string, string>

Environment variables

timeout · number

Maximum execution time in seconds (0 = no timeout)

Execution Artifacts

The response includes parsed artifacts from execution:

interface ExecuteResponse {
  exitCode: number;           // Exit status code
  result: string;            // Standard output
  artifacts?: {
    stdout: string;          // Same as result
    charts?: Chart[];        // Matplotlib chart metadata (Python)
  };
}

Command Execution

Running Shell Commands

Execute shell commands with full environment control:

const result = await sandbox.process.executeCommand(
  'echo "Hello World"'
);

console.log(result.artifacts.stdout); // Hello World
console.log(result.exitCode);         // 0

Commands with Working Directory

Specify the working directory for command execution:

const result = await sandbox.process.executeCommand(
  'ls -la',
  '/workspace/src' // working directory
);

Commands with Environment Variables

const result = await sandbox.process.executeCommand(
  'echo $MY_VAR',
  undefined,                    // use default working directory
  { MY_VAR: 'Custom Value' }    // environment variables
);

Commands with Timeout

const result = await sandbox.process.executeCommand(
  'sleep 10',
  undefined,  // working directory
  undefined,  // environment variables
  5           // timeout in seconds
);

command · string · required

Shell command to execute

cwd · string

Working directory for command execution. Defaults to sandbox working directory.

env · Record<string, string>

Environment variables to set for the command

timeout · number

Maximum time in seconds to wait (0 = wait indefinitely)

Session-Based Execution

Sessions maintain state between commands, ideal for multi-step workflows.

Creating a Session

const sessionId = 'my-session';
await sandbox.process.createSession(sessionId);

Executing Commands in a Session

Commands in a session share environment and context:

// Set an environment variable
await sandbox.process.executeSessionCommand(sessionId, {
  command: 'export FOO=BAR'
});

// Use it in a subsequent command
const response = await sandbox.process.executeSessionCommand(sessionId, {
  command: 'echo $FOO'
});

console.log(response.stdout); // BAR

Asynchronous Session Commands

Run long-running commands without blocking:

const response = await sandbox.process.executeSessionCommand(sessionId, {
  command: 'npm install && npm run build',
  runAsync: true
});

const commandId = response.cmdId;

// Check command status
const cmd = await sandbox.process.getSessionCommand(sessionId, commandId);
console.log(cmd.exitCode); // undefined while running

Streaming Session Logs

Stream output from asynchronous commands in real-time:

await sandbox.process.getSessionCommandLogs(
  sessionId,
  commandId,
  (stdout) => console.log('[STDOUT]:', stdout),
  (stderr) => console.log('[STDERR]:', stderr)
);

Sending Input to Session Commands

Send input to interactive commands:

const response = await sandbox.process.executeSessionCommand(sessionId, {
  command: 'read name && echo "Hello, $name"',
  runAsync: true
});

// Send input after a delay
await new Promise(resolve => setTimeout(resolve, 1000));
await sandbox.process.sendSessionCommandInput(
  sessionId,
  response.cmdId,
  'Alice\n'
);

Managing Sessions

// List all active sessions
const sessions = await sandbox.process.listSessions();

// Get session details
const session = await sandbox.process.getSession(sessionId);
console.log(session.commands); // Array of executed commands

// Delete a session
await sandbox.process.deleteSession(sessionId);

sessionId · string · required

Unique identifier for the session

request · SessionExecuteRequest · required

Command execution request

Show properties

command · string · required

The command to execute

runAsync · boolean

Execute asynchronously without waiting for completion

suppressInputEcho · boolean

Suppress echoing of input. Default is false.

Error Handling

Handle execution failures gracefully:

const result = await sandbox.process.executeCommand('invalid-command');

if (result.exitCode !== 0) {
  console.error('Command failed with exit code:', result.exitCode);
  console.error('Output:', result.artifacts.stdout);
}

Best Practices

Use sessions for related commands

When executing multiple related commands, use sessions to maintain environment state and avoid redundant setup.

Set appropriate timeouts

Always set timeouts for potentially long-running commands to prevent indefinite blocking.

Stream logs for long operations

For long-running operations, use async execution with log streaming to provide real-time feedback.

Clean up sessions

Delete sessions when finished to free up sandbox resources.

Related Resources

PTY Sessions

Interactive terminal sessions with full TTY support

Code Interpreter

Advanced Python code execution with context isolation