Skip to content

Process Execution

View as Markdown

Daytona runs shell commands and long-running processes in sandboxes. Commands run inside the sandbox, so untrusted or generated commands execute in isolation from your application.

Process execution is available through the process module of a sandbox. Every command runs as a process: you can run a command and wait for its result, or start it in the background and control it through a handle. Sessions are shell processes that keep state, such as the working directory and environment variables, across the commands that run in them. To run Python, TypeScript, and JavaScript code, see code execution. For interactive terminals, see pseudo terminal (PTY). For real-time logs from long-running processes, see log streaming.

Use cases

Section titled “Use cases”

Process execution is used when the work in a sandbox is a shell command or a program instead of a code snippet.

  • Build and test: package installs, compilers, and test runners run in the sandbox, and their exit code and output return to the application.
  • Agent tools: an agent runs shell commands as tools and reads their results.
  • Servers and workers: a web server or worker starts in the background, and the application checks its state, reads its logs, or stops it through its handle.
  • Multi-step shell work: a session keeps the working directory and environment variables, so a sequence of commands runs as it does in one terminal.
  • Interactive programs: input goes to a running command while its output streams back. Closing stdin tells the command that it has all its input.
  • Reconnects: an application reconnects to a process it started earlier and continues to read its output.
  • Commands as another user: a command runs as a specific user that exists in the image, or with a specific shell that the image installs.
  • Entrypoint checks: the details and logs of the sandbox entrypoint show whether the image’s main process started and what it printed.
  • Environment configuration: environment variables set once apply to every process started after the update, including PTYs, sessions, and Git commands.

Command execution

Section titled “Command execution”

Execute commands

Section titled “Execute commands”

Run a command and wait for it to exit. The result holds the exit code and output.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


response = sandbox.process.run("ls -la")
print(response.exit_code, response.stdout)
ParameterTypeDescription
timeoutfloatSets how many seconds run() waits. Without it, run() waits until the command exits. When the timeout elapses, reason is "timed_out", exit_code is None, and the command keeps running.

The response has the following fields:

FieldDescription
stdoutHolds the output of the stdout channel.
stderrHolds the output of the stderr channel.
outputHolds the output of both channels in recorded order.

Set the user and shell

Section titled “Set the user and shell”

Run a command as a specific user or with a specific shell. The user must exist in the image and the shell must be installed.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


response = sandbox.process.run("whoami", user="daytona", shell="bash")
print(response.output)

Update the environment

Section titled “Update the environment”

Set or remove environment variables for every process started in the sandbox after the update, including PTYs, sessions, and the git commands that git operations run. Running processes and sessions keep their environment. Removing a variable affects only variables set through an earlier update; variables defined by the image stay.

# Processes started after this call inherit the change
sandbox.update_env({"LOG_LEVEL": "debug"}, unset=["HTTP_PROXY"])


response = sandbox.process.run("echo $LOG_LEVEL")
print(response.stdout)
ParameterTypeDescription
envMapping[str, str]Adds or replaces variables. Each KEY=VALUE entry is at most 128 KiB, and env is at most 1 MiB in total.
unsetSequence[str]Removes variables. This parameter is keyword only.
  • macOS sandboxes also cap the environment that new processes inherit.
  • The cap counts the existing variables plus the update.
  • On macOS, the cap is 512 KiB, half of ARG_MAX.
  • On macOS, each variable counts 8 bytes in addition to its KEY=VALUE text.

Execute interactive commands

Section titled “Execute interactive commands”

Run a command that reads input. Start the command with stdin open, write input to it, and close stdin when the command has all its input.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


handle = sandbox.process.start("pip uninstall requests", stdin="open")


# Send input to the command
handle.stdin("y\n")
handle.stdin_eof()


wait = handle.wait()
page = handle.logs()
for frame in page.items:
    print(f"[{frame.channel}]: {frame.data}")
print(wait.exit_code)
ParameterTypeDescription
stdinstrSets the stdin of the command to "open" or "closed". The default is "closed".

Process control

Section titled “Process control”

Start a background process

Section titled “Start a background process”

Start a process without waiting for it to exit. The SDK returns a handle that you can use to wait for, read logs from, and stop the process.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


handle = sandbox.process.start("python -m http.server 8000")
print(handle.id)
  • The record and logs of a process started without name are removed 10 minutes after the process exits.
  • To keep the record and logs, pass name or keep_logs="until_cleanup".
  • See log retention.

List processes

Section titled “List processes”

List the processes in a sandbox. Filter the list by state, kind, session, name, or PID.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


running = sandbox.process.list(state="running")
for info in running.items:
    print(info.id, info.name, info.state, info.pid)

Process states

Section titled “Process states”
StateMeaning
startingThe record exists; the process has not been spawned yet.
provisioningCode execution only: the language kernel is being installed or started. Progress is reported on the setup log channel.
runningThe process has a PID and is executing.
terminalThe process has finished. reason, exitCode, and signal describe how.
ReasonMeaning
exitedExited on its own; exitCode is set. A code execution that raised an exception exits with 1.
signaledKilled by a signal; signal is set. wait reports bare names (TERM, KILL), the API reports SIGTERM, SIGKILL.
timed_outThe timeoutMs set at start elapsed; the process was killed with SIGKILL. Also returned by wait itself when its own long-poll window elapses first, with no exitCode.
lostThe process disappeared without the daemon observing its exit, for example after a sandbox stop and start, or when its session was deleted while it was still running.
failedThe process could not be started or ran into a daemon-side error.

Log retention

Section titled “Log retention”

Choose how long a process record and its logs are kept after the process exits. The policy is set when the process starts. Once a record is removed, the process can no longer be waited on or read. See log streaming for size caps and eviction.

PolicyBehavior
until_cleanupKept until the process is deleted (DELETE /processes/{id}). Default for processes started with a name; the SDK pty namespace also uses it.
on_exit_ttlKept for 10 minutes after exit, then removed. Default for unnamed processes; the SDK run methods always use it.
noneLogs are discarded as soon as the process exits. The record is kept for 10 minutes, so wait still returns the exit result.
from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


# Keep the record and logs until delete() is called
handle = sandbox.process.start("npm test", keep_logs="until_cleanup")
handle.wait()


for frame in handle.logs().items:
    print(frame.data, end="")
handle.delete()

Wait for a process

Section titled “Wait for a process”

Wait for a process to finish, or until a timeout elapses.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


handle = sandbox.process.start("npm run build")


# Wait up to 2 minutes; without timeout, wait() blocks until the process is terminal
result = handle.wait(timeout=120)
print(result.reason, result.exit_code)

Stop a process

Section titled “Stop a process”

Stop a running process by sending it a signal. The SDKs send the terminate signal.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


handle = sandbox.process.start("python -m http.server 8000")


# Sends SIGTERM
handle.kill()
ParameterTypeDescription
signalSignalNameSets the signal to send: TERM, KILL, INT, HUP, QUIT, USR1, or USR2. The default is "TERM".
escalate_afterfloatSends escalate_to if the process is still running after this many seconds. The value is at most 600.
escalate_toSignalNameSets the signal sent after escalate_after. The default is "KILL".
  • A command in a session cannot be signaled on its own.
  • To stop a command in a session, delete the session.

Reconnect to a process

Section titled “Reconnect to a process”

Reconnect to a process from another worker or process. Processes are addressed by ID, so any client with the sandbox ID and the process ID can wait for, read logs from, and stop the process. To reconnect to an interpreter context, see reconnect to a context.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


# Worker A: start the process and persist the handle
handle = sandbox.process.start("npm run build")
saved = handle.to_json()  # {"sandboxId": "...", "processId": "...", "kind": "exec"}


# Worker B: reconnect and wait for the same process
handle = sandbox.process.connect(saved)
result = handle.wait()
  • connect() takes the saved dict or a process ID and makes no request.
  • A process that does not exist, or a dict saved from another sandbox, fails on the first call that uses the handle.
  • A process name resolves only while the process runs.
  • After the process exits, reconnect by ID.

Entrypoint process

Section titled “Entrypoint process”

Get the details and logs of the sandbox entrypoint. It runs as a system process, so you can read it like any other process but not signal, write to, or delete it.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


# Entrypoint process details
info = sandbox.process.get("entrypoint")
print(f"Command: {info.argv or info.shell_command}")


# Entrypoint logs
handle = sandbox.process.connect("entrypoint")
for frame in handle.logs().items:
    print(f"[{frame.channel}]: {frame.data}")

Sessions

Section titled “Sessions”

A session is a long-lived shell that runs the commands you send to it. Commands in a session run one at a time, in order, and share the shell state, such as the working directory, exported variables, and functions. To run commands in parallel, use separate sessions or background processes.

A session is a process of kind session, and each command in it is an ordinary process with its own logs, exit code, timeout, and signals. Interrupting a command stops only that command, and the session keeps running. Sessions survive pause and resume, but not stop and start. Interpreter contexts run a language kernel instead of a shell.

Create a session

Section titled “Create a session”

Create a shell session. The working directory and environment variables of the session apply to all of its commands.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


session = sandbox.process.create_session(cwd="/tmp", env={"CI": "1"}, name="build-session")
print(session.id)
ParameterTypeDescription
cwdstrSets the working directory of the shell. The default is the home directory of the default user.
envMapping[str, str]Sets environment variables applied when the shell starts.
shellstrSets the path or name of the shell. On Linux and macOS, it must be a POSIX shell: bash, sh, dash, zsh, or ksh.
loginboolStarts a login shell when set to True.
namestrSets a name that commands can use in place of the session ID while the session is running.
  • create_session() returns a Session. Use it as a context manager to delete the session when the block exits.
  • session.to_json() and sandbox.process.connect_session() reconnect to a session without a request.

Execute session commands

Section titled “Execute session commands”

Run commands in a session. Shell state set by one command is available to the next. A command timeout starts when the command starts, after any commands queued ahead of it. When the timeout elapses, Daytona stops the command and the session keeps running.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


with sandbox.process.create_session() as session:
    # Shell state persists between commands
    session.run("cd /tmp && export STAGE=dev")
    result = session.run("pwd && echo $STAGE", execution_timeout=30)
    print(result.stdout)


    # Interrupt one command; the session keeps running
    command = session.start("sleep 600")
    command.kill(signal="INT")
ParameterTypeDescription
timeoutfloatSets how many seconds run() waits for the command.
execution_timeoutfloatSets how many seconds the command can run before Daytona stops it. The session keeps running.
namestrSets a name for the command process.

Get session status

Section titled “Get session status”

Get the status of a session, including the current working directory of its shell, and list the commands that ran in it.

info = session.get()
print(info.state, info.cwd)


listed = sandbox.process.list(session_id=session.id)
for proc in listed.items:
    print(f"Process: {proc.id}, Command: {proc.shell_command}, Exit Code: {proc.exit_code}")

List sessions

Section titled “List sessions”

List the shell sessions in a sandbox.

sessions = sandbox.process.list(kind="session")
for proc in sessions.items:
    print(proc.id, proc.state)

Get session command

Section titled “Get session command”

Get a command that ran in a session by its process ID.

command = sandbox.process.get("{processId}")
print(f"Command: {command.shell_command}, Exit Code: {command.exit_code}")

Delete a session

Section titled “Delete a session”

Delete a session. This ends its shell, stops its running commands, and removes the records of its commands.

session.delete()

Resource management

Section titled “Resource management”

Named processes keep their record and logs until you delete them. Delete a named process when you no longer need it; deleting stops the process if it is still running.

from daytona import Daytona


daytona = Daytona()
sandbox = daytona.v2.create()


handle = sandbox.process.start("sleep 3600", name="my-process")
try:
    pass  # Do work...
finally:
    handle.delete()  # kills the process if it is still running