Pseudo Terminal (PTY)

PTY endpoints let you create interactive terminal sessions with a persistent shell process. Connect via WebSocket for real-time bidirectional I/O, similar to SSH or a browser-based terminal.

Create a PTY session

Create a terminal session with a shell process.

By default, the shell starts when the PTY session is created. If you set lazy_start: true, Leap0 creates the PTY session first and waits to start the shell until the first WebSocket connection is opened for that session.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
session = sandbox.pty.create(
  session_id="my-terminal",
  cols=120,
  rows=40,
  cwd="/home/user",
  envs={"TERM": "xterm-256color"},
)

print(session.id, session.cwd, session.cols, session.rows)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/pty`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  id: "my-terminal",
  cols: 120,
  rows: 40,
  cwd: "/home/user",
  envs: { TERM: "xterm-256color" },
}),
})

const session = await res.json()
// session contains: id, cwd, envs, cols, rows, created_at, active, lazy_start

Lazy start example

Use lazy_start: true when you want to create the PTY session now but wait to start the shell until the first WebSocket connection.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
session = sandbox.pty.create(
  session_id="lazy-terminal",
  cwd="/workspace",
  cols=120,
  rows=40,
  lazy_start=True,
)

print(session.id, session.lazy_start)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/pty`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  id: "lazy-terminal",
  cwd: "/workspace",
  cols: 120,
  rows: 40,
  lazy_start: true,
}),
})

const session = await res.json()
console.log(session.id, session.lazy_start)

Connect via WebSocket

Open a WebSocket connection for interactive terminal I/O. All messages are binary frames containing raw terminal bytes.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
session = sandbox.pty.get("my-terminal")
connection = sandbox.pty.connect(session.id)
try:
  connection.send("ls -la
")
  print(connection.recv().decode("utf-8", errors="replace"), end="")
finally:
  connection.close()

// Example browser terminal UI wiring
const ws = new WebSocket(
`wss://api.leap0.dev/v1/sandbox/${sandboxId}/pty/${session.id}/connect`
)
ws.binaryType = "arraybuffer"

// Terminal output
ws.onmessage = (event) => {
const text = new TextDecoder().decode(event.data)
term.write(text)
}

// Terminal input
term.onData((data) => {
ws.send(new TextEncoder().encode(data))
})

Resize terminal

Change the terminal dimensions while connected.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
session = sandbox.pty.resize("my-terminal", cols=200, rows=50)
print(session.cols, session.rows)

await fetch(
`${apiUrl}/v1/sandbox/${sandboxId}/pty/${session.id}/resize`,
{
  method: "POST",
  headers: {
    authorization: apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ cols: 200, rows: 50 }),
}
)

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
for session in sandbox.pty.list():
  print(session.id, session.active)

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/pty`, {
headers: { authorization: apiKey },
})

const { items } = await res.json()
items.forEach(s => console.log(s.id, s.active))

Delete a PTY session

Kill the shell process and remove the session.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
sandbox.pty.delete("my-terminal")

await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/pty/${session.id}`, {
method: "DELETE",
headers: { authorization: apiKey },
})