ProcessHandle

class ProcessHandle()

Serializable handle for one daemon process.

ProcessHandle.init

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

ProcessHandle.sandbox_id

@property
def sandbox_id() -> str

ProcessHandle.process_id

@property
def process_id() -> str

ProcessHandle.id

@property
def id() -> str

ProcessHandle.kind

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

ProcessHandle.attach

def attach() -> None

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

ProcessHandle.delete

def delete() -> None

Delete the process record and retained logs, stopping it first.

ProcessHandle.from_json

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

Rehydrate a handle identity without making a network request.

ProcessHandle.get

def get() -> ProcessInfo

Fetch current process metadata.

ProcessHandle.kill

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

Send a signal and optional escalation signal.

ProcessHandle.logs

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

Read a cursor-replayable process log page.

ProcessHandle.ref

def ref() -> ProcessHandleRef

Return a typed handle identity.

ProcessHandle.resize

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

Resize a PTY process.

ProcessHandle.stdin

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

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

ProcessHandle.stdin_eof

def stdin_eof() -> None

Close stdin for an exec or PTY process.

ProcessHandle.stream_logs

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

Follow process logs with SSE while retaining cursor replay semantics.

ProcessHandle.to_json

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

Return a JSON-safe handle identity.

ProcessHandle.wait

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

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

AsyncProcessHandle

class AsyncProcessHandle()

Serializable handle for one daemon process.

AsyncProcessHandle.init

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

AsyncProcessHandle.to_json

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

Return a JSON-safe handle identity.

AsyncProcessHandle.from_json

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

Rehydrate a handle identity without making a network request.

AsyncProcessHandle.ref

def ref() -> ProcessHandleRef

Return a typed handle identity.

AsyncProcessHandle.bind

def bind(transport: AsyncTransport) -> AsyncProcessHandle

Return this handle bound to a transport.

AsyncProcessHandle.get

async def get() -> ProcessInfo

Fetch current process metadata.

AsyncProcessHandle.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.

AsyncProcessHandle.logs

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

Read a cursor-replayable process log page.

AsyncProcessHandle.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.

AsyncProcessHandle.stdin

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

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

AsyncProcessHandle.stdin_eof

async def stdin_eof() -> None

Close stdin for an exec or PTY process.

AsyncProcessHandle.kill

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

Send a signal and optional escalation signal.

AsyncProcessHandle.resize

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

Resize a PTY process.

AsyncProcessHandle.attach

def attach() -> None

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

AsyncProcessHandle.delete

async def delete() -> None

Delete the process record and retained logs, stopping it first.

Raises UnsupportedOperationError for a running code cell and for a session command that has not stopped within 5 s: delete its session.

ProcessService

class ProcessService()

Sandbox process namespace.

ProcessService.init

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

ProcessService.connect

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

Create a bound process handle without fetching metadata.

ProcessService.connect_session

def connect_session(session_id: str | Mapping[str, object]) -> Session

Bind a session id or serialized identity without making a request.

ProcessService.create_session

def create_session(*,
                   cwd: Optional[str] = None,
                   env: Optional[Mapping[str, str]] = None,
                   shell: Optional[str] = None,
                   login: Optional[bool] = None,
                   name: Optional[str] = None) -> Session

Create one persistent shell; cwd and env apply to all its commands.

ProcessService.get

def get(process_id: str) -> ProcessInfo

Fetch current process metadata by id or live name alias.

ProcessService.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]

ProcessService.run

def run(command: Optional[str] = None,
        *,
        argv: Optional[Sequence[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.

ProcessService.start

def start(command: Optional[str] = None,
          *,
          argv: Optional[Sequence[str]] = None,
          name: 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.

AsyncProcessService

class AsyncProcessService()

Sandbox process namespace.

AsyncProcessService.init

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

AsyncProcessService.create_session

async def create_session(*,
                         cwd: Optional[str] = None,
                         env: Optional[Mapping[str, str]] = None,
                         shell: Optional[str] = None,
                         login: Optional[bool] = None,
                         name: Optional[str] = None) -> AsyncSession

Create one persistent shell; cwd and env apply to all its commands.

shell must be a POSIX shell (bash, sh, dash, zsh, ksh) on Linux and macOS; another shell is refused when the session is created. On Windows, pwsh or powershell.

AsyncProcessService.connect_session

def connect_session(session_id: str | Mapping[str, object]) -> AsyncSession

Bind a session id or serialized identity without making a request.

AsyncProcessService.start

async def start(command: Optional[str] = None,
                *,
                argv: Optional[Sequence[str]] = None,
                name: 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) -> AsyncProcessHandle

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. For persistent shell state, use create_session.

: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

AsyncProcessService.run

async def run(command: Optional[str] = None,
              *,
              argv: Optional[Sequence[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. For persistent shell state, use create_session.

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.v2.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)

AsyncProcessService.connect

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

Create a bound process handle without fetching metadata.

AsyncProcessService.get

async def get(process_id: str) -> ProcessInfo

Fetch current process metadata by id or live name alias.

AsyncProcessService.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__(impl: AsyncPtyService, bridge: SyncBridge) -> None

PtyService.connect

def connect(process_id: str) -> ProcessHandle

Create a bound PTY handle.

PtyService.delete

def delete(process_id: str) -> None

PtyService.list

def list() -> ListResult[ProcessInfo]

PtyService.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) -> ProcessHandle

Start a detached PTY process.

AsyncPtyService

class AsyncPtyService()

PTY convenience namespace.

AsyncPtyService.init

def __init__(process: AsyncProcessService) -> None

AsyncPtyService.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) -> AsyncProcessHandle

Start a detached PTY process.

AsyncPtyService.connect

def connect(process_id: str) -> AsyncProcessHandle

Create a bound PTY handle.

AsyncPtyService.list

async def list() -> ListResult[ProcessInfo]

AsyncPtyService.delete

async def delete(process_id: str) -> None

Session

class Session()

One persistent shell whose commands run one at a time, in order.

Session.init

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

Session.sandbox_id

@property
def sandbox_id() -> str

Session.id

@property
def id() -> str

Session.delete

def delete() -> None

End this shell and remove it and all its commands.

Session.from_json

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

Rehydrate an unbound identity without making a request.

Session.get

def get() -> ProcessInfo

Fetch session metadata, including the shell’s live cwd.

Session.run

def run(command: str,
        *,
        stdin: StdinMode = 'closed',
        timeout: Optional[float] = None,
        execution_timeout: Optional[float] = None,
        name: Optional[str] = None,
        keep_logs: Optional[KeepLogs] = None) -> ProcessResult

Run a command in this shell and collect output; timeouts are seconds.

Session.start

def start(command: str,
          *,
          stdin: StdinMode = 'closed',
          execution_timeout: Optional[float] = None,
          name: Optional[str] = None,
          keep_logs: Optional[KeepLogs] = None) -> ProcessHandle

Queue a command and return its handle without waiting for exit.

Session.to_json

def to_json() -> _SessionIdentity

Return a JSON-safe identity for process.connect_session().

AsyncSession

class AsyncSession()

One persistent shell whose commands run one at a time, in order.

Directory changes, exports and functions carry over between commands. Set cwd and env when calling process.create_session(). Interrupt a running command with handle.kill(signal="INT"); the session survives. Sessions do not survive a sandbox stop/start. On Windows, interrupts stop external programs but cannot interrupt PowerShell loops or cmdlets, and commands cannot take stdin="open". After set -x or set -v in a session, later commands’ stderr also traces the daemon’s own lines that run each command.

AsyncSession.init

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

AsyncSession.to_json

def to_json() -> _SessionIdentity

Return a JSON-safe identity for process.connect_session().

AsyncSession.from_json

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

Rehydrate an unbound identity without making a request.

AsyncSession.run

async def run(command: str,
              *,
              stdin: StdinMode = 'closed',
              timeout: Optional[float] = None,
              execution_timeout: Optional[float] = None,
              name: Optional[str] = None,
              keep_logs: Optional[KeepLogs] = None) -> ProcessResult

Run a command in this shell and collect output; timeouts are seconds.

timeout bounds the caller’s wait without stopping the command; execution_timeout stops the command without ending the session. A command that has not stopped 5 s after its timeout (the shell could not interrupt it and it runs no process to kill) ends the session instead. In dash, BusyBox sh and mksh an interrupt leaves only the innermost shell function or sourced file, as it does in bash older than 4.4 (macOS’s /bin/bash) when a DEBUG trap is set.

AsyncSession.start

async def start(command: str,
                *,
                stdin: StdinMode = 'closed',
                execution_timeout: Optional[float] = None,
                name: Optional[str] = None,
                keep_logs: Optional[KeepLogs] = None) -> AsyncProcessHandle

Queue a command and return its handle without waiting for exit.

Interrupt it with handle.kill(signal="INT"); the shell survives. execution_timeout is a server-side deadline in seconds; the clock starts when the command starts, after any queued commands ahead of it.

AsyncSession.get

async def get() -> ProcessInfo

Fetch session metadata, including the shell’s live cwd.

AsyncSession.delete

async def delete() -> None

End this shell and remove it and all its commands.

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

ProcessKind

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

ProcessInfoKind

ProcessInfoKind = Literal['exec', 'pty', 'code', 'session', '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']

ProcessHandle

ProcessHandle.__init__

ProcessHandle.sandbox_id

ProcessHandle.process_id

ProcessHandle.id

ProcessHandle.kind

ProcessHandle.attach

ProcessHandle.delete

ProcessHandle.from_json

ProcessHandle.get

ProcessHandle.kill

ProcessHandle.logs

ProcessHandle.ref

ProcessHandle.resize

ProcessHandle.stdin

ProcessHandle.stdin_eof

ProcessHandle.stream_logs

ProcessHandle.to_json

ProcessHandle.wait

AsyncProcessHandle

AsyncProcessHandle.__init__

AsyncProcessHandle.to_json

AsyncProcessHandle.from_json

AsyncProcessHandle.ref

AsyncProcessHandle.bind

AsyncProcessHandle.get

AsyncProcessHandle.wait

AsyncProcessHandle.logs

AsyncProcessHandle.stream_logs

AsyncProcessHandle.stdin

AsyncProcessHandle.stdin_eof

AsyncProcessHandle.kill

AsyncProcessHandle.resize

AsyncProcessHandle.attach

AsyncProcessHandle.delete

ProcessService

ProcessService.__init__

ProcessService.connect

ProcessService.connect_session

ProcessService.create_session

ProcessService.get

ProcessService.list

ProcessService.run

ProcessService.start

AsyncProcessService

AsyncProcessService.__init__

AsyncProcessService.create_session

AsyncProcessService.connect_session

AsyncProcessService.start

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

AsyncProcessService.run

AsyncProcessService.connect

AsyncProcessService.get

AsyncProcessService.list

PtyService

PtyService.__init__

PtyService.connect

PtyService.delete

PtyService.list

PtyService.start

AsyncPtyService

AsyncPtyService.__init__

AsyncPtyService.start

AsyncPtyService.connect

AsyncPtyService.list

AsyncPtyService.delete

Session

Session.__init__

Session.sandbox_id

Session.id

Session.delete

Session.from_json

Session.get

Session.run

Session.start

Session.to_json

AsyncSession

AsyncSession.__init__

AsyncSession.to_json

AsyncSession.from_json

ProcessHandle.init

AsyncProcessHandle.init

ProcessService.init

AsyncProcessService.init

PtyService.init

AsyncPtyService.init

Session.init

AsyncSession.init