Interactive shells and TTY

インタラクティブな TTY セッションには Sandbox.shell() を使用します。生バイトのストリーミングに対応し、出力のバッファリングを行わない TerminalSession を返します。対話的な使用向けに設計されています。バッチでコマンドを実行する場合は、代わりに exec() を使用します。

認証を選択する

セクション内で CKS が指定されている場合を除き、これらの例はサーバーレスキャパシティ上で実行されます。サンドボックスを所有するアカウントの認証情報を選択してください。キーまたはトークンを取得するには、認証情報の選択と取得を参照してください。インストールコマンドは、有効化した Python 仮想環境内で実行してください。使用する認証情報のタブにある Python コードを、このページで実行する Python スクリプトと同じディレクトリに sandbox_auth.py として保存してください。このファイルに保存されるのはどの認証方式を使うかという設定であり、認証情報そのものは含まれません。各例ではこのファイルから AUTH をインポートし、新しいサンドボックスまたは Session を作成するたびに明示的に渡します。

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 を指定して Session を作成すると、その Session が所有するサンドボックスも認証されます。サンドボックスへの再接続、一覧表示、クリーンアップを行う際も、同じ認証情報を使用してください。

シェルセッション

サンドボックスを作成し、インタラクティブシェルのセッションを開きます。コマンドを指定せずに 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 でファイア・アンド・フォーゲットです。

シェルセッションの終了

stdin を閉じるか、終了コマンドを送信して、シェルセッションを終了します。

terminal.stdin.writeline("exit").result()  # リモートシェルに終了を要求します
# または
terminal.stdin.close().result()            # stdin ストリームを閉じます

リモートプロセスが終了すると、シェルセッションが完了します。terminal.wait() または terminal.result() を呼び出して、終了コードが返されるまでブロックします。

ローカルターミナルをアタッチする

実行中のサンドボックスを自分のターミナルから操作するには、ローカルターミナルを raw モードに切り替え、その入力を shell() セッションに転送します。次のスクリプトは、ID を指定して既存のサンドボックスにアタッチし、キー入力をサンドボックス内の Bash シェルに転送します。シェルが終了すると、ローカルターミナルの設定を元に戻します。このスクリプトは termios を使用するため、macOS または Linux で動作します。スクリプトを attach_sandbox.py という名前で sandbox_auth.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 モード

サンドボックス

サンドボックスを使用する

サンドボックスの管理

リファレンス

Interactive shells and TTY

認証を選択する

シェルセッション

コマンドを送信して出力を読み取る

ターミナルのサイズ変更

シェルセッションの終了

ローカルターミナルをアタッチする

コマンドと使用例

関連項目

​認証を選択する

​シェルセッション

​コマンドを送信して出力を読み取る

​ターミナルのサイズ変更

​シェルセッションの終了

​ローカルターミナルをアタッチする

​コマンドと使用例

​関連項目

認証を選択する

シェルセッション

コマンドを送信して出力を読み取る

ターミナルのサイズ変更

シェルセッションの終了

ローカルターミナルをアタッチする

コマンドと使用例

関連項目