Open-source, secure environment with real-world tools for enterprise-grade agents.
Python agentaiai-agentai-agentscode-interpretercopilotdevelopmentdevtoolsgptgpt-4javascriptllmnextjsopenaipythonreactsoftwaretypescript
from typing import Dict, Optional
import httpx
from e2b.api.client_async import get_envd_api
from packaging.version import Version
from protobuf import Oneof
from e2b.envd.process import process_connect, process_pb
from e2b.connection_config import (
Username,
ConnectionConfig,
KEEPALIVE_PING_HEADER,
KEEPALIVE_PING_INTERVAL_SEC,
STREAM_INPUT_TIMEOUT,
)
from e2b.envd.api import acheck_sandbox_health
from e2b.envd.rpc import akill_process, ahandle_rpc_exception_with_health
from e2b.envd.utils import (
authentication_header,
extract_start_pid,
timeout_to_ms,
)
from e2b.envd.client_async import as_stream, create_rpc_client, first_event
from e2b.sandbox.commands.command_handle import PtySize
from e2b.sandbox_async.commands.command_input_handle import AsyncCommandInputHandle
from e2b.sandbox_async.commands.command_handle import (
AsyncCommandHandle,
OutputHandler,
PtyOutput,
)
class Pty:
"""
Module for interacting with PTYs (pseudo-terminals) in the sandbox.
"""
def __init__(
self,
envd_api_url: str,
connection_config: ConnectionConfig,
envd_version: Version,
envd_api: httpx.AsyncClient,
) -> None:
self._connection_config = connection_config
self._envd_version = envd_version
self._rpc = create_rpc_client(
process_connect.ProcessClient,
envd_api_url,
connection_config,
)
self._envd_api = envd_api
# The health probe run after a request failed goes without the
# connection retries, so a sandbox that cannot be reached is not tried
# all over again (see `get_transport`).
self._envd_health_api = get_envd_api(
connection_config, envd_api_url, retry_connect=False
)
async def _check_health(self) -> Optional[bool]:
return await acheck_sandbox_health(self._envd_health_api)
async def kill(
self,
pid: int,
request_timeout: Optional[float] = None,
) -> bool:
"""
Kill PTY.
:param pid: Process ID of the PTY
:param request_timeout: Timeout for the request in **seconds**
:return: `true` if the PTY was killed, `false` if the PTY was not found
"""
return await akill_process(
self._rpc,
pid,
self._connection_config.get_request_timeout(request_timeout),
self._check_health,
)
async def send_stdin(
self,
pid: int,
data: bytes,
request_timeout: Optional[float] = None,
) -> None:
"""
Send input to a PTY.
:param pid: Process ID of the PTY
:param data: Input data to send
:param request_timeout: Timeout for the request in **seconds**
"""
try:
await self._rpc.send_input(
process_pb.SendInputRequest(
process=process_pb.ProcessSelector(selector=Oneof("pid", pid)),
input=process_pb.ProcessInput(
input=Oneof("pty", data),
),
),
timeout_ms=timeout_to_ms(
self._connection_config.get_request_timeout(request_timeout)
),
)
except Exception as e:
raise await ahandle_rpc_exception_with_health(e, self._check_health)
def stream_input(
self,
pid: int,
*,
timeout: Optional[float] = STREAM_INPUT_TIMEOUT,
) -> AsyncCommandInputHandle:
"""Open an ordered input handle to a PTY.
:param pid: Process ID of the PTY.
:param timeout: Timeout in seconds; defaults to ``STREAM_INPUT_TIMEOUT``
(60 seconds). ``0`` or ``None`` disables the timeout.
:return: Handle for queuing ordered input with ``send()`` and ending the
stream with ``close()``.
:raises NotFoundException: If the PTY does not exist; surfaced by the
handle's ``send()`` or ``close()``.
:raises TimeoutException: If the stream timeout expires; surfaced by
the handle's ``send()`` or ``close()``.
"""
return AsyncCommandInputHandle(
self._rpc,
pid,
"pty",
timeout,
self._check_health,
)
async def create(
self,
size: PtySize,
on_data: OutputHandler[PtyOutput],
user: Optional[Username] = None,
cwd: Optional[str] = None,
envs: Optional[Dict[str, str]] = None,
timeout: Optional[float] = 60,
request_timeout: Optional[float] = None,
) -> AsyncCommandHandle:
"""
Start a new PTY (pseudo-terminal).
:param size: Size of the PTY
:param on_data: Callback to handle PTY data
:param user: User to use for the PTY
:param cwd: Working directory for the PTY
:param envs: Environment variables for the PTY
:param timeout: Timeout for the PTY in **seconds**
:param request_timeout: Timeout for opening the stream in **seconds** — the wait until envd confirms with a start event. The running stream is bounded by `timeout`
:return: Handle to interact with the PTY
"""
envs = dict(envs) if envs else {}
envs.setdefault("TERM", "xterm-256color")
envs.setdefault("LANG", "C.UTF-8")
envs.setdefault("LC_ALL", "C.UTF-8")
events = as_stream(
self._rpc.start(
process_pb.StartRequest(
process=process_pb.ProcessConfig(
cmd="/bin/bash",
envs=envs,
args=["-i", "-l"],
cwd=cwd,
),
pty=process_pb.PTY(
size=process_pb.PTY.Size(rows=size.rows, cols=size.cols)
),
),
headers={
**authentication_header(self._envd_version, user),
KEEPALIVE_PING_HEADER: str(KEEPALIVE_PING_INTERVAL_SEC),
},
timeout_ms=timeout_to_ms(timeout),
)
)
try:
start_event = await first_event(
events, self._connection_config.get_request_timeout(request_timeout)
)
pid = extract_start_pid(start_event, "start process")
return AsyncCommandHandle(
pid=pid,
handle_kill=lambda: self.kill(pid),
events=events,
on_pty=on_data,
check_health=self._check_health,
)
except Exception as e:
try:
await events.aclose()
except Exception:
pass
raise await ahandle_rpc_exception_with_health(e, self._check_health)
async def connect(
self,
pid: int,
on_data: OutputHandler[PtyOutput],
timeout: Optional[float] = 60,
request_timeout: Optional[float] = None,
) -> AsyncCommandHandle:
"""
Connect to a running PTY.
:param pid: Process ID of the PTY to connect to. You can get the list of running PTYs using `sandbox.pty.list()`.
:param on_data: Callback to handle PTY data
:param timeout: Timeout for the PTY connection in **seconds**. Using `0` will not limit the connection time
:param request_timeout: Timeout for opening the stream in **seconds** — the wait until envd confirms with a start event. The running stream is bounded by `timeout`
:return: Handle to interact with the PTY
"""
events = as_stream(
self._rpc.connect(
process_pb.ConnectRequest(
process=process_pb.ProcessSelector(selector=Oneof("pid", pid)),
),
timeout_ms=timeout_to_ms(timeout),
headers={
KEEPALIVE_PING_HEADER: str(KEEPALIVE_PING_INTERVAL_SEC),
},
)
)
try:
start_event = await first_event(
events, self._connection_config.get_request_timeout(request_timeout)
)
pid = extract_start_pid(start_event, "connect to process")
return AsyncCommandHandle(
pid=pid,
handle_kill=lambda: self.kill(pid),
events=events,
on_pty=on_data,
check_health=self._check_health,
)
except Exception as e:
try:
await events.aclose()
except Exception:
pass
raise await ahandle_rpc_exception_with_health(e, self._check_health)
async def resize(
self,
pid: int,
size: PtySize,
request_timeout: Optional[float] = None,
) -> None:
"""
Resize PTY.
Call this when the terminal window is resized and the number of columns and rows has changed.
:param pid: Process ID of the PTY
:param size: New size of the PTY
:param request_timeout: Timeout for the request in **seconds**
"""
try:
await self._rpc.update(
process_pb.UpdateRequest(
process=process_pb.ProcessSelector(selector=Oneof("pid", pid)),
pty=process_pb.PTY(
size=process_pb.PTY.Size(rows=size.rows, cols=size.cols),
),
),
timeout_ms=timeout_to_ms(
self._connection_config.get_request_timeout(request_timeout)
),
)
except Exception as e:
raise await ahandle_rpc_exception_with_health(e, self._check_health)