Process

Process and session execution interface for a Sandbox.

Supports single-command execution, code execution, long-running sessions, and PTY terminal sessions.

Methods

executeCommand()

public ExecuteResponse executeCommand(String command)

Executes a shell command with default options.

Parameters:

• command String - command to execute

Returns:

• ExecuteResponse - execution result

Throws:

• DaytonaException - if execution fails

executeCommand()

public ExecuteResponse executeCommand(String command, String cwd, Map<String, String> env, Integer timeout)

Executes a shell command.

The command is run by the first available of zsh, bash or sh in the sandbox, which is zsh in the default snapshots. Quote arguments that contain glob characters, for example pip install -e '.[test]', or wrap bash-specific scripts in bash -c '...'.

The call returns when the command finishes. To start a long-running process such as a server, run it in the background with its output redirected, e.g. python3 -m http.server 8000 > server.log 2>&1 &, or use a session command with runAsync set. A background process that keeps the command's output open (cmd & without a redirect) can block the call until that process exits.

Tools in the sandbox may report the host's CPU count and memory (for example nproc or Runtime.availableProcessors()) rather than the sandbox's own limits. Size worker pools from the sandbox's CPU and memory instead, e.g. pytest -n 2 rather than pytest -n auto.

Parameters:

• command String - command to execute
• cwd String - working directory, or null to use sandbox default
• env Map<String, String> - environment variables to set for the command
• timeout Integer - timeout in seconds

Returns:

• ExecuteResponse - execution result

Throws:

• DaytonaException - if execution fails

codeRun()

public ExecuteResponse codeRun(String code)

Executes source code using Sandbox language tooling.

Parameters:

• code String - source code to execute

Returns:

• ExecuteResponse - execution result

Throws:

• DaytonaException - if execution fails

codeRun()

public ExecuteResponse codeRun(String code, Map<String, String> env, Integer timeout)

Parameters:

• code String -
• env Map<String, String> -
• timeout Integer -

Returns:

• ExecuteResponse -

codeRun()

public ExecuteResponse codeRun(String code, List<String> argv, Map<String, String> env, Integer timeout)

Parameters:

• code String -
• argv List<String> -
• env Map<String, String> -
• timeout Integer -

Returns:

• ExecuteResponse -

createSession()

public void createSession(String sessionId)

Creates a persistent background session.

Parameters:

• sessionId String - unique session identifier

Throws:

• DaytonaException - if session creation fails

getSession()

public Session getSession(String sessionId)

Returns session metadata.

Parameters:

• sessionId String - session identifier

Returns:

• Session - session metadata

Throws:

• DaytonaException - if retrieval fails

getEntrypointSession()

public Session getEntrypointSession()

Returns entrypoint session metadata.

Returns:

• Session - entrypoint session metadata

Throws:

• DaytonaException - if retrieval fails

executeSessionCommand()

public SessionExecuteResponse executeSessionCommand(String sessionId, SessionExecuteRequest req)

Executes a command in an existing session.

Parameters:

• sessionId String - session identifier
• req SessionExecuteRequest - execution request

Returns:

• SessionExecuteResponse - command execution response

Throws:

• DaytonaException - if execution fails

getSessionCommand()

public Command getSessionCommand(String sessionId, String commandId)

Returns metadata for a command executed in a session.

Parameters:

• sessionId String - session identifier
• commandId String - command identifier

Returns:

• Command - command metadata

Throws:

• DaytonaException - if retrieval fails

getSessionCommandLogs()

public SessionCommandLogsResponse getSessionCommandLogs(String sessionId, String commandId)

Returns logs for a command executed in a session.

Parameters:

• sessionId String - session identifier
• commandId String - command identifier

Returns:

• SessionCommandLogsResponse - command logs

Throws:

• DaytonaException - if retrieval fails

getEntrypointLogs()

public SessionCommandLogsResponse getEntrypointLogs()

Returns one-shot logs for the sandbox entrypoint session.

Returns:

• SessionCommandLogsResponse - entrypoint logs

Throws:

• DaytonaException - if retrieval fails

getEntrypointLogs()

public void getEntrypointLogs(Consumer<String> onStdout, Consumer<String> onStderr)

Streams logs for the sandbox entrypoint session via WebSocket.

Parameters:

• onStdout Consumer<String> - callback for stdout chunks
• onStderr Consumer<String> - callback for stderr chunks

Throws:

• DaytonaException - if streaming fails

sendSessionCommandInput()

public void sendSessionCommandInput(String sessionId, String commandId, String data)

Sends input data to a command executed in a session.

Parameters:

• sessionId String - session identifier
• commandId String - command identifier
• data String - input text to send

Throws:

• DaytonaException - if sending input fails

deleteSession()

public void deleteSession(String sessionId)

Deletes a session.

Parameters:

• sessionId String - session identifier

Throws:

• DaytonaException - if deletion fails

listSessions()

public List<Session> listSessions()

Lists all sessions in the Sandbox.

Returns:

• List\<Session\> - session list

Throws:

• DaytonaException - if listing fails

createPty()

public PtyHandle createPty(PtyCreateOptions options)

Creates a PTY terminal session.

Parameters:

• options PtyCreateOptions - PTY options, or null to use defaults

Returns:

• PtyHandle - PTY handle for streaming I/O and lifecycle operations

Throws:

• DaytonaException - if PTY session creation fails

connectPty()

public PtyHandle connectPty(String sessionId)

Connects to an existing PTY terminal session.

Parameters:

• sessionId String - PTY session identifier

Returns:

• PtyHandle - PTY handle for streaming I/O and lifecycle operations

Throws:

• DaytonaException - if websocket connection setup fails

connectPty()

public PtyHandle connectPty(String sessionId, PtyCreateOptions options)

Connects to an existing PTY terminal session.

Parameters:

• sessionId String - PTY session identifier
• options PtyCreateOptions - PTY options, used for data callback configuration

Returns:

• PtyHandle - PTY handle for streaming I/O and lifecycle operations

Throws:

• DaytonaException - if websocket connection setup fails

listPtySessions()

public List<PtySessionInfo> listPtySessions()

Lists PTY sessions in the Sandbox.

Returns:

• List\<PtySessionInfo\> - PTY session information list

Throws:

• DaytonaException - if listing fails

getPtySessionInfo()

public PtySessionInfo getPtySessionInfo(String sessionId)

Returns PTY session information.

Parameters:

• sessionId String - PTY session identifier

Returns:

• PtySessionInfo - PTY session information

Throws:

• DaytonaException - if retrieval fails

resizePtySession()

public void resizePtySession(String sessionId, int cols, int rows)

Resizes an active PTY session.

Parameters:

• sessionId String - PTY session identifier
• cols int - terminal width in columns
• rows int - terminal height in rows

Throws:

• DaytonaException - if resize fails

killPtySession()

public void killPtySession(String sessionId)

Terminates a PTY session.

Parameters:

• sessionId String - PTY session identifier

Throws:

• DaytonaException - if termination fails