ProcessHandle

class ProcessHandle()

Serializable handle for one daemon process.

ProcessHandle.init

def __init__(sandbox_id: str,
             process_id: str,
             transport: Optional[AsyncTransport] = None,
             kind: Optional[ProcessKind] = None) -> None

ProcessHandle.from_json

@classmethod
def from_json(value: Mapping[str, str]) -> ProcessHandle

Rehydrate a handle identity without making a network request.

ProcessHandle.wait

async def wait(*, timeout: Optional[float] = None) -> WaitResult

Wait for terminal state using the daemon long-poll contract.

timeout is the caller wait budget in seconds; 0 waits unbounded.

ProcessHandle.logs

async def logs(*,
               cursor: Optional[str] = None,
               limit: Optional[int] = None,
               encoding: LogEncoding = 'text') -> LogPage

Read a cursor-replayable process log page.

ProcessHandle.stream_logs

async def stream_logs(*,
                      cursor: Optional[str] = None,
                      encoding: LogEncoding = 'text') -> AsyncIterator[LogFrame]

Follow process logs with SSE while retaining cursor replay semantics.

ProcessHandle.stdin

async def stdin(data: Union[str, bytes], *, eof: bool = False) -> None

Write stdin to an exec or PTY process created with stdin='open'.

ProcessHandle.kill

async def kill(*,
               signal: SignalName = 'TERM',
               escalate_after: Optional[float] = None,
               escalate_to: SignalName = 'KILL') -> None

Send a signal and optional escalation signal.

ProcessHandle.attach

def attach() -> None

Attach is optional in Python because no runtime WebSocket dependency is bundled.

ProcessHandle.cleanup

async def cleanup() -> None

Delete the process record and retained logs.

ProcessService

class ProcessService()

Sandbox process namespace.

ProcessService.init

def __init__(sandbox_id: str,
             transport: AsyncTransport,
             language: Optional[str] = None) -> None

ProcessService.start

async def start(command: Optional[str] = None,
                *,
                argv: Optional[Sequence[str]] = None,
                name: Optional[str] = None,
                session_id: Optional[str] = None,
                cwd: Optional[str] = None,
                env: Optional[Mapping[str, str]] = None,
                user: Optional[str] = None,
                shell: Optional[str] = None,
                login: Optional[bool] = None,
                stdin: StdinMode = 'closed',
                execution_timeout: Optional[float] = None,
                terminal: Optional[TerminalSize] = None,
                keep_logs: Optional[KeepLogs] = None) -> ProcessHandle

Start a detached process and return a handle immediately.

Unlike run, this returns as soon as the daemon has started the process. Use the returned ProcessHandle to stream logs (handle.stream_logs()), wait for exit (handle.wait()), or kill (handle.kill()). This is the right choice for long-running servers — call start() once, then poll the port or stream logs to confirm the server is ready.

Shell selection. A string command runs through the sandbox shell (bash, else sh; pin another with shell=). Quote globs and brackets (pip install -e '.[test]'). Use argv= to bypass the shell for untrusted input. With session_id the command runs in that session's shell instead, where argv and execution_timeout do not apply.

:param command: Shell command string; mutually exclusive with argv. :param argv: Argument vector for shell-free execution. :param cwd: Working directory inside the sandbox. :param env: Extra environment variables merged into the process environment. :param shell: Shell binary to use (e.g. "bash"); overrides auto-detection. :param execution_timeout: Server-side deadline in seconds. The daemon kills the process tree when this expires. :returns: Bound ProcessHandle — logs, wait, and kill are available immediately.

Example — start an HTTP server and wait for it to be ready::

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

poll or stream logs; the process keeps running in the background

ProcessService.run

async def run(command: Optional[str] = None,
              *,
              argv: Optional[Sequence[str]] = None,
              session_id: Optional[str] = None,
              cwd: Optional[str] = None,
              env: Optional[Mapping[str, str]] = None,
              user: Optional[str] = None,
              shell: Optional[str] = None,
              login: Optional[bool] = None,
              stdin: StdinMode = 'closed',
              timeout: Optional[float] = None,
              execution_timeout: Optional[float] = None,
              name: Optional[str] = None,
              terminal: Optional[TerminalSize] = None,
              keep_logs: Optional[KeepLogs] = None) -> ProcessResult

Start a process, wait for its shell to exit, and collect its output.

The common case is one round trip: the daemon starts the process, parks the request until it exits (or timeout expires), and returns the output inline. A process that outlives the wait window or produces more output than fits in one page falls back to split calls automatically.

The result holds the output the daemon still has when the call returns: its per-process log is bounded, so very large output loses its oldest frames, and a result that timed out collects only the first few log pages.

Shell selection. A string command runs through the sandbox shell (bash, else sh; pin another with shell=). Quote globs and brackets (pip install -e '.[test]') so the command means the same under any shell. Use argv= to bypass the shell entirely, which is the safe form for untrusted arguments. With session_id the command runs in that session's shell instead, where argv and execution_timeout do not apply.

Background processes. The call returns when the shell exits. If the command forks a background child that holds its output descriptors open (e.g. python3 -m http.server 8000 &), the daemon waits at most ~2 seconds for output to drain and then returns; output the child writes later is not part of the result. For a long-running server prefer start, which returns a ProcessHandle immediately, or redirect: nohup cmd > server.log 2>&1 &.

:param command: Shell command string; mutually exclusive with argv. :param argv: Argument vector for shell-free execution. :param cwd: Working directory inside the sandbox. :param env: Extra environment variables merged into the process environment. :param shell: Shell binary to use (e.g. "bash"); overrides auto-detection. :param timeout: Caller wait budget in seconds. Omit to wait until the process ends. Does not kill the process on expiry. :param execution_timeout: Server-side deadline in seconds. The daemon kills the process tree when this expires. :returns: daytona.types.ProcessResult with stdout, stderr, output, exit_code, and reason.

Example::

result = await sandbox.process.run("pip install httpx") if result.exit_code != 0: raise RuntimeError(result.stderr)

ProcessService.connect

def connect(process_id: Union[str, Mapping[str, str]]) -> ProcessHandle

Create a bound process handle without fetching metadata.

ProcessService.get

async def get(process_id: str) -> ProcessInfo

Fetch current process metadata by id or live name alias.

ProcessService.list

async def list(*,
               state: Optional[ProcessStateFilter] = None,
               kind: Optional[ProcessKind] = None,
               session_id: Optional[str] = None,
               name: Optional[str] = None,
               pid: Optional[int] = None) -> ListResult[ProcessInfo]

PtyService

class PtyService()

PTY convenience namespace.

PtyService.init

def __init__(process: ProcessService) -> None

PtyService.start

async def start(command: Optional[str] = None,
                *,
                cols: int = 80,
                rows: int = 24,
                cwd: Optional[str] = None,
                env: Optional[Mapping[str, str]] = None,
                name: Optional[str] = None) -> ProcessHandle

Start a detached PTY process.

PtyService.connect

def connect(process_id: str) -> ProcessHandle

Create a bound PTY handle.

PtyService.list

async def list() -> ListResult[ProcessInfo]

PtyService.delete

async def delete(process_id: str) -> None

ProcessInfo

@dataclass(frozen=True)
class ProcessInfo()

Serializable daemon process DTO.

Attributes:

id str
kind ProcessInfoKind
state ProcessState
name Optional[str] = None
pid Optional[int] = None
system bool = False
session_id Optional[str] = None
shell_command Optional[str] = None
argv Optional[List[str]] = None
code Optional[str] = None
language Optional[str] = None
shell Optional[str] = None
resolved_shell Optional[str] = None
login Optional[bool] = None
cwd Optional[str] = None
user Optional[str] = None
stdin Optional[ProcessStdinMode] = None
execution_timeout Optional[float] = None
terminal Optional[TerminalSize] = None
keep_logs Optional[ProcessKeepLogs] = None
exit_code Optional[int] = None
signal Optional[str] = None
reason Optional[WaitReason] = None
created_at Optional[str] = None
started_at Optional[str] = None
exited_at Optional[str] = None
truncated_head bool = False
first_available_cursor Optional[str] = None
last_cursor Optional[str] = None
raw_kind Optional[str] = None
raw_state Optional[str] = None
raw_stdin Optional[str] = None
raw_keep_logs Optional[str] = None
raw_reason Optional[str] = None

ProcessHandleRef

@dataclass(frozen=True)
class ProcessHandleRef()

JSON-safe process handle identity.

Attributes:

sandbox_id str
process_id str
kind Optional[ProcessKind] = None

WaitResult

@dataclass(frozen=True)
class WaitResult()

Result returned by process wait.

Attributes:

exit_code Optional[int] = None
signal Optional[str] = None
reason Optional[WaitReason] = None
raw_reason Optional[str] = None

LogFrame

@dataclass(frozen=True)
class LogFrame()

One replayable process ledger frame.

Attributes:

cursor str
channel str
data str
timestamp Optional[int] = None

LogPage

@dataclass(frozen=True)
class LogPage()

A cursor-addressed process log page.

Attributes:

items List[LogFrame]
next_cursor Optional[str] = None
truncated_head bool = False
first_available_cursor Optional[str] = None

ProcessResult

@dataclass(frozen=True)
class ProcessResult()

Process run result with collected output.

Attributes:

process_id str
exit_code Optional[int]
signal Optional[str]
reason Optional[WaitReason]
stdout str = ''
stderr str = ''
output str = ''
raw_reason Optional[str] = None

TerminalSize

@dataclass(frozen=True)
class TerminalSize()

PTY terminal dimensions.

Attributes:

cols int
rows int

SyncProcessHandle

class SyncProcessHandle()

Serializable handle for one daemon process.

SyncProcessHandle.init

def __init__(impl: ProcessHandle, bridge: SyncBridge) -> None

SyncProcessHandle.sandbox_id

@property
def sandbox_id() -> str

SyncProcessHandle.process_id

@property
def process_id() -> str

SyncProcessHandle.id

@property
def id() -> str

SyncProcessHandle.kind

@property
def kind() -> Literal['exec', 'pty', 'code'] | None

SyncProcessHandle.attach

def attach() -> None

Attach is optional in Python because no runtime WebSocket dependency is bundled.

SyncProcessHandle.cleanup

def cleanup() -> None

Delete the process record and retained logs.

SyncProcessHandle.from_json

@classmethod
def from_json(value: Mapping[str, str]) -> SyncProcessHandle

Rehydrate a handle identity without making a network request.

SyncProcessHandle.get

def get() -> ProcessInfo

Fetch current process metadata.

SyncProcessHandle.kill

def kill(*,
         signal: SignalName = 'TERM',
         escalate_after: Optional[float] = None,
         escalate_to: SignalName = 'KILL') -> None

Send a signal and optional escalation signal.

SyncProcessHandle.logs

def logs(*,
         cursor: Optional[str] = None,
         limit: Optional[int] = None,
         encoding: LogEncoding = 'text') -> LogPage

Read a cursor-replayable process log page.

SyncProcessHandle.ref

def ref() -> ProcessHandleRef

Return a typed handle identity.

SyncProcessHandle.resize

def resize(cols: int, rows: int) -> None

Resize a PTY process.

SyncProcessHandle.stdin

def stdin(data: Union[str, bytes], *, eof: bool = False) -> None

Write stdin to an exec or PTY process created with stdin='open'.

SyncProcessHandle.stdin_eof

def stdin_eof() -> None

Close stdin for an exec or PTY process.

SyncProcessHandle.stream_logs

def stream_logs(*,
                cursor: Optional[str] = None,
                encoding: LogEncoding = 'text') -> Iterator[LogFrame]

Follow process logs with SSE while retaining cursor replay semantics.

SyncProcessHandle.to_json

def to_json() -> Dict[str, str]

Return a JSON-safe handle identity.

SyncProcessHandle.wait

def wait(*, timeout: Optional[float] = None) -> WaitResult

Wait for terminal state using the daemon long-poll contract.

SyncProcessService

class SyncProcessService()

Sandbox process namespace.

SyncProcessService.init

def __init__(impl: ProcessService, bridge: SyncBridge) -> None

SyncProcessService.connect

def connect(process_id: Union[str, Mapping[str, str]]) -> SyncProcessHandle

Create a bound process handle without fetching metadata.

SyncProcessService.get

def get(process_id: str) -> ProcessInfo

Fetch current process metadata by id or live name alias.

SyncProcessService.list

def list(*,
         state: Optional[ProcessStateFilter] = None,
         kind: Optional[ProcessKind] = None,
         session_id: Optional[str] = None,
         name: Optional[str] = None,
         pid: Optional[int] = None) -> ListResult[ProcessInfo]

SyncProcessService.run

def run(command: Optional[str] = None,
        *,
        argv: Optional[Sequence[str]] = None,
        session_id: Optional[str] = None,
        cwd: Optional[str] = None,
        env: Optional[Mapping[str, str]] = None,
        user: Optional[str] = None,
        shell: Optional[str] = None,
        login: Optional[bool] = None,
        stdin: StdinMode = 'closed',
        timeout: Optional[float] = None,
        execution_timeout: Optional[float] = None,
        name: Optional[str] = None,
        terminal: Optional[TerminalSize] = None,
        keep_logs: Optional[KeepLogs] = None) -> ProcessResult

Start a process, wait for its shell to exit, and collect its output.

SyncProcessService.start

def start(command: Optional[str] = None,
          *,
          argv: Optional[Sequence[str]] = None,
          name: Optional[str] = None,
          session_id: Optional[str] = None,
          cwd: Optional[str] = None,
          env: Optional[Mapping[str, str]] = None,
          user: Optional[str] = None,
          shell: Optional[str] = None,
          login: Optional[bool] = None,
          stdin: StdinMode = 'closed',
          execution_timeout: Optional[float] = None,
          terminal: Optional[TerminalSize] = None,
          keep_logs: Optional[KeepLogs] = None) -> SyncProcessHandle

Start a detached process and return a handle immediately.

SyncPtyService

class SyncPtyService()

PTY convenience namespace.

SyncPtyService.init

def __init__(impl: PtyService, bridge: SyncBridge) -> None

SyncPtyService.connect

def connect(process_id: str) -> SyncProcessHandle

Create a bound PTY handle.

SyncPtyService.delete

def delete(process_id: str) -> None

SyncPtyService.list

def list() -> ListResult[ProcessInfo]

SyncPtyService.start

def start(command: Optional[str] = None,
          *,
          cols: int = 80,
          rows: int = 24,
          cwd: Optional[str] = None,
          env: Optional[Mapping[str, str]] = None,
          name: Optional[str] = None) -> SyncProcessHandle

Start a detached PTY process.

ProcessKind

ProcessKind = Literal['exec', 'pty', 'code']

ProcessInfoKind

ProcessInfoKind = Literal['exec', 'pty', 'code', 'unknown']

ProcessStateFilter

ProcessStateFilter = Literal['running', 'terminal', 'all']

ProcessState

ProcessState = Literal['starting', 'provisioning', 'running', 'terminal', 'unknown']

KeepLogs

KeepLogs = Literal['until_cleanup', 'on_exit_ttl', 'none']

StdinMode

StdinMode = Literal['closed', 'open']

ProcessKeepLogs

ProcessKeepLogs = Literal['until_cleanup', 'on_exit_ttl', 'none', 'unknown']

ProcessStdinMode

ProcessStdinMode = Literal['closed', 'open', 'unknown']

WaitReason

WaitReason = Literal['exited', 'signaled', 'timed_out', 'lost', 'failed', 'unknown']

On this page

Computersfor Agents