Skip to main content
Desktop APIs require a desktop-capable template. PTY sessions are available for interactive terminal workflows in running sandboxes. Idle PTY streams remain connected while the sandbox is running. A WebSocket close without a pty_exited message is surfaced as a transport disconnect.

​
Desktop

from nullspace import Sandbox

with Sandbox.create(template="desktop") as sandbox:
    width, height = sandbox.desktop.screen_size()
    display = sandbox.desktop.display_info()
    sandbox.desktop.type("hello")
    png = sandbox.desktop.screenshot()
    jpeg = sandbox.desktop.screenshot_compressed(format="jpeg", quality=70)
    print(width, height, display.virtual_screen.width, len(png), len(jpeg))

​
Managed viewer

stream = sandbox.desktop.stream.start()
print(stream.viewer_url)
sandbox.desktop.set_clipboard_text("copied")
print(sandbox.desktop.get_clipboard_text())
sandbox.desktop.stream.stop()

​
Input, windows, and recordings

sandbox.desktop.move(100, 100)
sandbox.desktop.left_click()
sandbox.desktop.right_click(200, 200)
sandbox.desktop.hotkey("ctrl+l")
sandbox.desktop.open("https://example.com")

for window in sandbox.desktop.list_windows():
    print(window.id, window.title)

recording = sandbox.desktop.start_recording(name="demo")
finished = sandbox.desktop.stop_recording(recording.id)
sandbox.desktop.download_recording(finished.id, local_path="./desktop.mp4")

​
PTY

session = sandbox.pty.create_session(cols=100, rows=30)
chunks = []
session.send_input("pwd\nexit\n")
session.wait(on_data=lambda chunk: chunks.append(chunk.decode("utf-8")), timeout=5)
print("".join(chunks))
PTY sessions expose a string session_id for reconnect and management helpers. id is an alias for session_id. Numeric pid reconnect remains available for legacy scripts. 
session = sandbox.pty.create_session(cwd="/workspace")
session_id = session.session_id
session.disconnect()

reattached = sandbox.pty.connect(
    session_id=session_id,
    on_data=lambda chunk: print(chunk.decode("utf-8"), end=""),
)
reattached.send_input("echo reattached\n")
Manage existing PTY sessions by session_id: 
sessions = sandbox.pty.list_sessions()
session_id = sessions[0].session_id
info = sandbox.pty.get_session_info(session_id)
sandbox.pty.resize_session(session_id, 140, 40)
sandbox.pty.kill_session(session_id)
Concept: Create. API reference: screenshot, startDesktopStream, websocketUpgrade, listPtySessions, and killPtySession.