Process Execution

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

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

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)

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

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)

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)

Process control

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)

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

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.

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

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

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()

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()

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

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

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)

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")

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

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

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

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

session.delete()

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