Interactive shells and TTY

대화형 TTY 세션에는 Sandbox.shell()을 사용하세요. 이 메서드는 대화형 사용을 위해 설계된 TerminalSession을 반환하며, 출력 버퍼링 없이 원시 바이트 스트리밍을 제공합니다. 일괄 명령어 실행에는 대신 exec()을 사용하세요.

인증 선택

섹션에서 CKS를 지정하지 않는 한 이 예시는 서버리스 용량에서 실행됩니다. 샌드박스를 소유한 계정의 사용자 인증 정보를 선택하세요. 키 또는 토큰을 획득하는 방법은 사용자 인증 정보 선택 및 조회를 참조하세요. 설치 명령어는 활성화된 Python 가상 환경에서 실행하세요. 사용 중인 사용자 인증 정보 탭의 Python 코드를 sandbox_auth.py로 저장하되, 이 페이지에서 실행할 Python script와 같은 디렉터리에 두세요. 이 파일에는 사용자 인증 정보 자체가 아니라 어떤 인증 방식을 사용할지만 저장됩니다. 예시에서는 이 파일에서 AUTH를 임포트하여 새 샌드박스나 세션을 만들 때마다 명시적으로 전달합니다.

Forge API 키
CoreWeave API 액세스 토큰

SDK의 W&B 인증 전략으로 Forge API 키를 사용하세요.

uv pip install 'cwsandbox[wandb]>=1.14.2'
export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

CoreWeave 조직의 토큰을 사용하세요.

uv pip install 'cwsandbox>=1.14.2'
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

CKS 배치를 사용하려면 CoreWeave 토큰을 선택하고 러너를 활성화한 다음, 샌드박스를 생성할 때 또는 SandboxDefaults에서 placement_mode="cks"를 설정하세요. auth=AUTH로 세션을 생성하면 해당 세션이 소유한 샌드박스도 함께 인증됩니다. 샌드박스에 다시 연결하거나 목록을 조회하거나 정리할 때도 동일한 사용자 인증 정보를 사용하세요.

셸 세션

샌드박스를 생성하고 대화형 셸 세션을 엽니다. 명령어 없이 Sandbox.run()을 호출하면 기본 장기 실행 명령어를 사용합니다. 이후 예시는 이 컨텍스트가 여전히 활성 상태라고 가정합니다.

from sandbox_auth import AUTH
from cwsandbox import Sandbox

with Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH) as sandbox:
    terminal = sandbox.shell(
        ["/bin/bash"],
        width=80,
        height=24,
    )

shell()은 항상 TTY를 할당하고 stdin을 활성화합니다. 반환된 TerminalSession은 UTF-8 디코딩이나 인코딩을 거치지 않고 원시 바이트를 스트림하므로 터미널 이스케이프 시퀀스와 바이너리 출력을 안전하게 처리할 수 있습니다.

명령어 전송 및 출력 조회

터미널 세션이 열린 상태에서 stdin에 명령어를 쓰고 원격 셸에서 병합된 바이트 출력을 스트림으로 받아오세요.

import sys

terminal.stdin.writeline("echo hello").result()
terminal.stdin.writeline("ls -la /tmp").result()
terminal.stdin.writeline("exit").result()

# 원시 바이트 출력을 순회합니다
for chunk in terminal.output:
    sys.stdout.buffer.write(chunk)
    sys.stdout.buffer.flush()  # 세션 실행 중 출력이 표시되도록 플러시합니다.

# 종료 코드를 조회합니다
exit_code = terminal.wait(timeout=5.0)

TerminalSession은 출력을 버퍼링하지 않습니다. stdout과 stderr는 하나의 원시 바이트 스트림으로 병합되어 terminal.output으로 전달됩니다. 결과에는 별도의 stdout 또는 stderr 속성이 없습니다. terminal.output을 계속해서 조회하세요. 조회를 중단하면 크기가 제한된 큐에서 백프레셔가 발생하여 원격 세션이 멈춥니다.

터미널 크기 조정

터미널 크기가 변경될 때 크기 조정 메시지를 전송하세요.

terminal.resize(120, 40)

resize()는 TerminalSession에서 fire-and-forget입니다.

셸 세션 종료

stdin을 닫거나 exit 명령어를 전송하여 셸 세션을 종료하세요:

terminal.stdin.writeline("exit").result()  # 원격 셸에 종료를 요청하세요
# 또는
terminal.stdin.close().result()            # stdin 스트림을 닫으세요

원격 프로세스가 종료되면 셸 세션이 완료됩니다. 종료 코드가 반환될 때까지 대기하려면 terminal.wait() 또는 terminal.result()를 호출하세요.

로컬 터미널 연결

실행 중인 샌드박스에서 자신의 터미널로 작업하려면 로컬 터미널을 raw 모드로 전환하고 입력을 shell() 세션으로 전달하세요. 다음 스크립트는 ID를 사용해 기존 샌드박스에 연결하고, 키 입력을 샌드박스의 Bash 셸로 전달하며, 셸이 종료되면 로컬 터미널 설정을 복원합니다. 이 스크립트는 termios를 사용하므로 macOS 또는 Linux에서 실행할 수 있습니다. 스크립트를 sandbox_auth.py와 같은 디렉터리에 attach_sandbox.py로 저장하세요.

attach_sandbox.py

import os
import shutil
import sys
import termios
import threading
import tty

from cwsandbox import Sandbox
from sandbox_auth import AUTH

if not sys.stdin.isatty() or not sys.stdout.isatty():
    raise SystemExit("Run this script in an interactive terminal.")

sandbox = Sandbox.from_id(sys.argv[1], auth=AUTH).result()
size = shutil.get_terminal_size()
terminal = sandbox.shell(["/bin/bash"], width=size.columns, height=size.lines)
fd = sys.stdin.fileno()
saved = termios.tcgetattr(fd)

def forward_input():
    while data := os.read(fd, 1024):
        terminal.stdin.write(data).result()
    terminal.stdin.close().result()

try:
    tty.setraw(fd)
    threading.Thread(target=forward_input, daemon=True).start()
    for chunk in terminal.output:
        sys.stdout.buffer.write(chunk)
        sys.stdout.buffer.flush()
    result = terminal.result()
finally:
    termios.tcsetattr(fd, termios.TCSADRAIN, saved)
    terminal.stdin.close().result()

raise SystemExit(result.returncode)

[SANDBOX-ID]를 실행 중인 샌드박스의 ID로 바꾼 다음, 대화형 터미널에서 스크립트를 실행하세요.

python attach_sandbox.py [SANDBOX-ID]

스크립트는 원격 셸의 종료 코드를 반환하며 종료됩니다.

명령어 및 사용 사례

사용 사례	접근 방식
터미널에서 일회성 명령어	`cwsandbox exec [ID] echo hello`
터미널에서 대화형 셸	`cwsandbox sh [ID]`
스크립트 실행, 출력 캡처하다 (SDK)	`exec(["python", "script.py"])`
대화형 셸 세션 (SDK)	`shell(["/bin/bash"])`
명령어에 입력 전송 (SDK)	`exec(["cat"], stdin=True)`
터미널 애플리케이션 (vim, htop)	`shell(["vim"])` + CLI raw mode

참고 자료

명령어 실행 - exec()로 명령어를 실행하세요.
샌드박스 로깅 - 컨테이너 로그를 스트리밍하세요.

샌드박스

샌드박스 사용하기

샌드박스 관리

레퍼런스

Interactive shells and TTY

인증 선택

셸 세션

명령어 전송 및 출력 조회

터미널 크기 조정

셸 세션 종료

로컬 터미널 연결

명령어 및 사용 사례

참고 자료

​인증 선택

​셸 세션

​명령어 전송 및 출력 조회

​터미널 크기 조정

​셸 세션 종료

​로컬 터미널 연결

​명령어 및 사용 사례

​참고 자료

인증 선택

셸 세션

명령어 전송 및 출력 조회

터미널 크기 조정

셸 세션 종료

로컬 터미널 연결

명령어 및 사용 사례

참고 자료