Sign Up

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']

On this page

ProcessHandleProcessHandle.__init__ProcessHandle.sandbox_idProcessHandle.process_idProcessHandle.idProcessHandle.kindProcessHandle.attachProcessHandle.deleteProcessHandle.from_jsonProcessHandle.getProcessHandle.killProcessHandle.logsProcessHandle.refProcessHandle.resizeProcessHandle.stdinProcessHandle.stdin_eofProcessHandle.stream_logsProcessHandle.to_jsonProcessHandle.waitAsyncProcessHandleAsyncProcessHandle.__init__AsyncProcessHandle.to_jsonAsyncProcessHandle.from_jsonAsyncProcessHandle.refAsyncProcessHandle.bindAsyncProcessHandle.getAsyncProcessHandle.waitAsyncProcessHandle.logsAsyncProcessHandle.stream_logsAsyncProcessHandle.stdinAsyncProcessHandle.stdin_eofAsyncProcessHandle.killAsyncProcessHandle.resizeAsyncProcessHandle.attachAsyncProcessHandle.deleteProcessServiceProcessService.__init__ProcessService.connectProcessService.connect_sessionProcessService.create_sessionProcessService.getProcessService.listProcessService.runProcessService.startAsyncProcessServiceAsyncProcessService.__init__AsyncProcessService.create_sessionAsyncProcessService.connect_sessionAsyncProcessService.startpoll or stream logs; the process keeps running in the backgroundAsyncProcessService.runAsyncProcessService.connectAsyncProcessService.getAsyncProcessService.listPtyServicePtyService.__init__PtyService.connectPtyService.deletePtyService.listPtyService.startAsyncPtyServiceAsyncPtyService.__init__AsyncPtyService.startAsyncPtyService.connectAsyncPtyService.listAsyncPtyService.deleteSessionSession.__init__Session.sandbox_idSession.idSession.deleteSession.from_jsonSession.getSession.runSession.startSession.to_jsonAsyncSessionAsyncSession.__init__AsyncSession.to_jsonAsyncSession.from_jsonAsyncSession.runAsyncSession.startAsyncSession.getAsyncSession.deleteProcessInfoProcessHandleRefWaitResultLogFrameLogPageProcessResultTerminalSizeProcessKindProcessInfoKindProcessStateFilterProcessStateKeepLogsStdinModeProcessKeepLogsProcessStdinModeWaitReason

Computersfor Agents

Isolated sandboxes for agent code,
ready in under 100 ms.

Start for Free