Use Terminals

Polyaxon supports several terminal workflows for service runs. Pick the smallest access mode that fits the task.

This page continues from the Sandbox Quick Start. The Python examples reuse its sandbox client; the CLI examples reuse its quick-start project and RUN_UUID variable. The component created there enables the sandbox, tmux, and SSH plugins.

Terminal Options

One-Off Commands

result = sandbox.process.exec(command=["python", "-V"])
print(result.stdout, end="")
print(result.stderr, end="")

polyaxon sandbox exec -p quick-start -uid $RUN_UUID -- python -V

Use streaming for long-running commands:

with sandbox.process.exec_stream(
    command=["sh", "-lc", "pip list"],
) as events:
    for event in events:
        print(event)

polyaxon sandbox exec -p quick-start -uid $RUN_UUID --stream -- sh -lc 'pip list'

Detached Commands

Background commands keep running after the Python call returns or the CLI exits:

sandbox.fs.upload_file(
    local_path="./sandbox/train.py",
    path="/workspace/train.py",
)
background = sandbox.process.exec_bg(
    command=["python", "train.py"],
    workdir="/workspace",
)
print(background.id)

polyaxon sandbox upload -p quick-start -uid $RUN_UUID \
  ./sandbox/train.py /workspace/train.py
EXEC_ID=$(polyaxon sandbox exec -p quick-start -uid $RUN_UUID --detach -- sh -lc 'python train.py')

Read logs later:

for chunk in background.iter_stdout(timeout=60, interval=0.5):
    print(chunk, end="")
status = background.wait(timeout=60)
print(status.state, status.exit_code)

polyaxon sandbox logs -p quick-start -uid $RUN_UUID $EXEC_ID

Interactive Shell

The Python PTY API exposes raw terminal frames for applications that implement their own terminal loop:

pty = sandbox.pty.create(command=["sh"], workdir="/workspace")
try:
    with sandbox.pty.attach(pty.pty_id, replay_bytes=1024) as terminal:
        terminal.send_stdin(b"pwd\n")
        print(terminal.recv())
finally:
    sandbox.pty.delete(pty.pty_id)

For a human interactive shell, use the CLI:

polyaxon sandbox shell -p quick-start -uid $RUN_UUID

Use this for quick inspection and short-lived debugging.

Reconnectable Shell

Enable plugins.tmux when you want a terminal session that survives browser, websocket, or local terminal disconnects:

plugins:
  tmux: true

Attach with:

polyaxon ops shell -p quick-start -uid $RUN_UUID

At a shell prompt, detach without ending the shell:

/opt/polyaxon/bin/tmux detach-client

The default keyboard shortcut is Ctrl+B, release both keys, then press lowercase d. On macOS, use Control (⌃), not Command (⌘). Do not type exit when you intend to detach: exiting the last tmux pane destroys the session, and the next polyaxon ops shell starts a new shell without its exported variables.

See the Python process and PTY references for programmatic access. See the sandbox CLI, operations CLI, and SSH CLI references for interactive terminal commands.