tcb-sandbox（tcb 沙箱）

TCB Sandbox Skill

Operate tcb-remote-workspace safely and consistently through @tcb-sandbox/cli.

Runtime Assumptions

This skill assumes the following tcb-sandbox runtime behavior:

• one sandbox instance is affinitized to one session
• one instance may handle concurrent tool requests within that same session
• idle instances may freeze and later wake on incoming requests
• instances rotate and are destroyed after TTL expiration

When troubleshooting, consider lifecycle transitions (freeze/wake/rotate) as first-class causes of transient behavior.

When To Use This Skill

Use this skill when a user asks to do any of the following against a TRW workspace:

• inspect workspace health or capabilities
• read/write/edit/search files via TRW tools
• run session-scoped shell commands
• create/send-input/read-output/resize/kill session PTY processes
• manage session secrets
• upload/download binary files
• discover or open preview ports
• snapshot and restore workspace state

Use direct local shell/file operations instead when the user explicitly asks to operate only on the local machine and not on TRW.

Preconditions

Before any operation, confirm all required runtime inputs exist:

1. CLI is installed (tcb-sandbox command is available)
2. endpoint is available (TCB_SANDBOX_ENDPOINT or --endpoint)
3. session is available for non-health commands (TCB_SANDBOX_SESSION_ID or --session-id)

If any precondition is missing, stop and request the missing input with a concrete example command.

First-Run Bootstrap

Use this bootstrap sequence when the environment may be fresh.

Step A: Detect CLI availability

tcb-sandbox --version

If command is missing, install CLI:

pnpm add -g @tcb-sandbox/cli@0.3.9

Then re-run:

tcb-sandbox --version

Step B: Detect minimum runtime config

Do not read arbitrary local environment variables. Only use explicit user-provided values or the two declared runtime variables:

• TCB_SANDBOX_ENDPOINT
• TCB_SANDBOX_SESSION_ID

Optional extra headers can be passed only when required by gateway policy:

• TCB_SANDBOX_HEADERS_JSON

If either value is missing, stop and ask user to pass explicit flags (--endpoint, --session-id) or set only those exact variables.

Step C: First connectivity smoke test

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" health

Only continue to tool/file/preview actions after health passes.

Safety Rules

Always follow these rules:

1. Never print plaintext secrets unless the user explicitly requests secret retrieval.
2. Prefer top-level secret tools (secrets_set/get/list/delete) and avoid plaintext exposure in shell history.
3. Do not assume session reuse across users; session id is the security boundary.
4. For mutating operations (write, edit, bash, files upload, secrets-store set/delete, pty-service create/send_input/resize/kill), restate intent before execution.
5. For destructive actions, log a high-risk notice and execute directly.
6. Keep logs concise and redact sensitive headers (Authorization, Token, Cookie, session-like headers).
7. Never request or read unrelated local credentials; only handle secrets explicitly named and approved by the user for TRW session use.

High-Risk Operation Notice Template

Before running bash, any secrets-store mutation/retrieval command, or PTY lifecycle operations (pty-service create/send_input/resize/kill), emit a high-risk notice in this format:

High-risk action notice: <exact command intent>, target session=<session-id>, expected impact=<what changes>.

Do not require any interactive confirmation step. Continue execution after logging the notice.

Standard Execution Flow

Run operations in this order unless the user asks otherwise.

1) Connectivity and readiness

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" health

If not ready, report readiness failure and stop.

2) Capability discovery

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" docs
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" docs

If /api/docs is temporarily unavailable, CLI fallback docs are acceptable for read-only planning, but warn that runtime behavior may differ.

3) Session-scoped operation

For all non-health operations, include session id:

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" <command>

4) Result reporting

Return:

• what command was executed
• whether it succeeded
• key output fields only
• next recommended step

Capability-First Flow (Updated)

When the task involves session abilities (secrets, binary transfer, preview, PTY, git snapshot, MCP, CLI wrappers, or skills), always run the metadata workflow before executing. Authoritative copy also ships in MCP instructions and .workspace-info.md (see repo src/capability-agent-guide.ts).

Mandatory order (do not skip describe)

1. capability-list — discover ids. Add --reveal-paths when you need absolute paths for capability-register or to read skill files under packagePath.
2. capability-describe <id> — read executionBy, executionVia, actions, and route/schema hints. Never guess how to run the capability.
3. Install/register branch (only for new custom capabilities)

- capability-install <id> ... — instruction only; nothing is installed server-side and the capability list does not change yet. - Run returned steps in the sandbox (usually bash). - capability-register <id> ... with final --command / --server-name+--command / --package-path. - capability-list again immediately after successful register — refresh what exists in the session so you do not “forget” the new capability. - Call capability-describe again if needed (e.g. on the new id from the refreshed list). Skip steps 3 entirely when a built-in or already-registered capability already satisfies the task. Alternative (stdio MCP servers only) — session mcporter CRUD: - List keys: list-mcp-servers → available_mcp_servers. - Add: add-mcp-servers --data '{“serverName”:”…”,”command”:”…”}' or --server-name <name> --command <cmd>. Same server name already present = no overwrite (幂等). - Delete: remove-mcp-servers --server-name <name> or --data '{“serverNames”:[“a”,”b”]}'. Built-in server names cloudbase / memory cannot be removed. - Update: remove-mcp-servers then add-mcp-servers with new command/args/env. - Discover & call server tools: mcporter 'list <server> --schema --output json' for tool schemas; mcporter “call '<server>.<tool>(param: \”value\”)”' for invocation. - If your MCP client only exposes capability_* tools, use capability-register / capability-remove (kind=mcp) and read .mcporter/mcporter.json instead.

1. Execute using the route from describe

- executionBy=capability + executionVia=capability_invoke → native only: capability-invoke <id> <action> --parameters '{…}'. Native ids: secrets-store, files-transfer, preview-service, pty-service, git-archive. - executionVia=bash → bash '<command>'. - executionVia=bash+mcporter → mcporter “call '<server>.<tool>(...)”'. - executionBy=caller + executionVia=caller_defined (skills) → read the skill entryFile under packagePath and follow it on the agent side; the remote workspace does not auto-run skill logic.

Failure and fallback

• If capability_invoke returns *not executed by capability_invoke*: stop invoking; re-run capability_describe and follow sandbox/caller routing.
• If the ability is missing from capability_list: use bash / read / grep / glob and PATH discovery (generic tools are intentionally not all listed as capabilities).

Thin MCP / HTTP tool surfaces

• Most non-native capabilities are metadata-only; execution follows capability_describe hints, not capability_invoke.
• When top-level tools (secrets_*, preview_*, files_*, pty_*) exist, prefer them for UX parity with HTTP; when they are not exposed, capability_invoke on native ids is the supported path (same handlers underneath).

Command Playbooks

Health

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" health

Docs and tool discovery

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" docs
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" help read

Core tools (read / write / edit / bash / grep / glob / ls / batch)

# Read a file (line-numbered output)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  read README.md

# Read a specific line range
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  read README.md --offset 10 --limit 50

# Write or overwrite a file
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  write hello.txt --content 'hello world'

# Write from stdin
echo 'content from stdin' | tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" \
  --session-id "$TCB_SANDBOX_SESSION_ID" write hello.txt --content-stdin

# Edit a file (targeted string replacement)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  edit README.md --old 'old text' --new 'new text'

# Edit — replace all occurrences
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  edit config.json --old '"debug": false' --new '"debug": true' --replace-all

# Execute a shell command
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  bash 'ls -la'

# Bash with options
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  bash 'pnpm build' --timeout 120000 --cwd /workspace/project

# Bash dry-run (simulated execution)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  bash 'rm -rf node_modules' --mode dry_run

# Search file contents by regex
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  grep 'TODO' --path src --include '*.ts'

# Search with case sensitivity
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  grep 'Error' --case-sensitive --limit 20

# Find files by glob pattern
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  glob '**/*.test.ts'

# Glob with ignore patterns
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  glob '**/*' --path src --ignore '**/node_modules/**' --ignore '**/.git/**'

# List directory contents
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" ls
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" ls src --ignore '*.map'

# Batch multiple tool calls
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  batch --data '{"tool_calls":[{"name":"read","arguments":{"path":"a.txt"}},{"name":"bash","arguments":{"command":"ls"}}]}'

Git Push

Push a workspace snapshot to a remote git repository.

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  git-push 'snapshot: fix auth bug'

Workspace Snapshot / Restore

Snapshot and restore workspace state via S3. Requires SNAPSHOT_S3_* env vars on the server.

# Create a snapshot (async — returns snapshot_id immediately)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  snapshot create

# Create with extra excludes
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  snapshot create --exclude dist .env

# Create including everything (skip default excludes)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  snapshot create --include-all

# Check snapshot status
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  snapshot status <snapshot_id>

# List all session snapshot tasks
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  snapshot status

# Restore from snapshot (merge mode — keeps existing files)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  snapshot restore <snapshot_id>

# Restore with replace mode (clean then extract, keeps .git)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  snapshot restore <snapshot_id> --mode replace

# Cross-session restore (use another session's snapshot_id)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$OTHER_SESSION_ID" \
  snapshot restore <snapshot_id_from_session_A>

Session mcporter (add / remove / list MCP servers)

# List configured MCP server names
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  list-mcp-servers

# Add a stdio MCP server (idempotent by name)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  add-mcp-servers --server-name my-mcp --command npx --args -y @scope/mcp-server

# Add with env variables
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  add-mcp-servers --server-name fetch-mcp --command uvx --env API_KEY=secret

# Add by JSON payload (supports Cursor/VS Code mcpServers fragment shape)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  add-mcp-servers --data '{"mcpServers":{"url_fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}'

# Remove one server by name
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  remove-mcp-servers --server-name my-mcp

# Remove multiple servers
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  remove-mcp-servers --server-names srv-a srv-b

# Discover tools of a specific MCP server
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  mcporter 'list my-mcp --schema --output json'

# Call a server tool
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  mcporter "call 'my-mcp.toolName(param: \"value\")'"

Capability management

# List all capabilities (built-in + registered)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-list

# List with absolute paths (needed for capability_register of skills)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-list --reveal-paths

# Describe one capability — read executionBy / executionVia / actions / schema
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-describe git-archive

# Get installation guidance (instruction-only, does not modify registry)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-install my-mcp --kind mcp --server-name my-mcp

# Register after external installation (example: MCP server)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-register my-mcp --kind mcp --server-name my-mcp --command /usr/local/bin/my-mcp

# Register a skill
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-register my-skill --kind skill --package-path /workspace/.skills/my-skill --entry-file SKILL.md

# Remove a registered capability (built-in capabilities cannot be removed)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-remove my-mcp

# Invoke a native capability action
# (ids: secrets-store / files-transfer / preview-service / pty-service / git-archive)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-invoke git-archive push_snapshot --parameters '{"message":"snapshot"}'

Secrets (primary via CLI subcommands)

Set:

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  secrets set TRW_SESSION_SECRET --value '<USER_APPROVED_SECRET_VALUE>'

Get (plaintext — only when user explicitly asks):

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  secrets get TRW_SESSION_SECRET

List keys (metadata only, no plaintext):

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  secrets list

Delete:

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  secrets delete TRW_SESSION_SECRET

Binary files

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  files upload ./local.bin artifacts/local.bin

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  files download artifacts/local.bin ./downloaded.bin

PTY

PTY subcommands call top-level PTY tools.

# Create a PTY process
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  pty create --command bash --args -lc 'sleep 60'

# Create with custom cwd (workspace-relative or absolute)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  pty create --command bash --cwd /workspace/project --cols 120 --rows 40

# Send text input (auto base64 encoded)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  pty send-input 12345 --text 'echo hello\
'

# Send base64 payload directly
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  pty send-input 12345 --base64 'aGVsbG8K'

# Resize terminal
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  pty resize 12345 --cols 120 --rows 40

# Read buffered output
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  pty read-output 12345 --after-seq 0 --limit 64

# Kill process
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  pty kill 12345 --signal SIGTERM

Preview

Preview subcommands call top-level preview tools.

# List previewable ports
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" preview ports

# Build preview URL for a port
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" preview url 3000

# Open preview URL in browser (macOS/Linux/Windows)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" preview open 3000

# Print URL without opening browser
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" preview open 3000 --print-only

Standard Tools Quick Map

Use this quick map to pick the right tool fast.

• read: read a text file from workspace
• write: create or overwrite a text file
• edit: apply targeted string-level edits to existing text
• grep: search file content by pattern
• glob: search files by name/path patterns
• ls: inspect directory structure
• bash: run shell commands in session workspace
• batch: execute multiple tool calls with one request

bash mode note:

• default mode is execute when mode is omitted
• pass mode=dry_run explicitly to request simulated execution with risk summary, decision, and file-level changeSet
• Background processes are NOT reliably preserved after a bash call returns (orphan processes may be reaped). For long-running servers, prefer pty create --command '<cmd>' or bash 'tmux new-session -d -s <name> "<cmd>"'. Subshell syntax (cmd > /tmp/log 2>&1 &) can work for simple cases but is fragile. Do NOT use nohup.

Selection rule:

• if task is content lookup, start with read or grep
• if task is structure discovery, use ls or glob
• if task mutates text, choose edit first and write only when full overwrite is intended
• if task needs runtime state (build, test, start service), use bash

Case Study: Secrets Lifecycle

Goal:

• store API key safely, validate availability, rotate value, and remove stale key

Commands:

# 1) Set
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-invoke secrets-store set --parameters '{"key":"TRW_SESSION_SECRET","value":"<USER_APPROVED_SECRET_VALUE_V1>"}'

# 2) Confirm key exists (metadata only)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-invoke secrets-store list

# 3) Optional: verify value retrieval only when user explicitly asks
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-invoke secrets-store get --parameters '{"key":"TRW_SESSION_SECRET"}'

# 4) Rotate to new value
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-invoke secrets-store set --parameters '{"key":"TRW_SESSION_SECRET","value":"<USER_APPROVED_SECRET_VALUE_V2>"}'

# 5) Delete deprecated key
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  capability-invoke secrets-store delete --parameters '{"key":"TRW_SESSION_SECRET_OLD"}'

Reporting checklist:

• key name(s) affected
• action type (set/rotate/delete)
• whether plaintext was intentionally exposed
• follow-up recommendation (for example, restart service to reload env)

Case Study: Preview Bring-Up and Diagnosis

Goal:

• start a service, discover exposed ports, return stable preview URL, and diagnose failures

Commands:

# 1) Start service in workspace (example)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  bash 'pnpm run dev'

# 2) Discover available preview ports
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  preview ports

# 3) Build preview URL for selected port
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  preview url 3000

# 4) If port not listed, diagnose process and bind state
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  bash 'ps -ef | head -n 30 && ss -lntp | head -n 30'

Troubleshooting hints:

• no port found: check whether app started successfully and is listening on 0.0.0.0
• unexpected port: inspect app logs and runtime config (PORT, framework defaults)
• preview unreachable: verify session id consistency between start command and preview query

Task Templates

Use these templates for common user intents.

Template 1: Read then edit a remote file

Goal:

• inspect a file and then apply a targeted content update

Commands:

# 1) Read current content
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  read src/app.ts

# 2) Apply edit (example payload; adjust for actual edit tool schema)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  edit src/app.ts --old 'foo' --new 'bar'

# 3) Re-read to verify change
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  read src/app.ts

Report format:

• target path
• before/after key delta
• verification result

Template 2: Upload artifact and verify checksum/size

Goal:

• ship a local file into session workspace and verify transfer

Commands:

# 1) Upload
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  files upload ./dist/build.tar.gz artifacts/build.tar.gz

# 2) Verify by reading metadata via bash tool
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  bash 'ls -lh artifacts/build.tar.gz && shasum -a 256 artifacts/build.tar.gz'

Report format:

• remote path
• file size
• checksum

Template 3: Start service and return preview URL

Goal:

• run service in workspace and provide reachable preview URL

Commands:

# 1) Start service (example)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  bash 'pnpm run dev'

# 2) Discover previewable ports
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" preview ports

# 3) Build final URL
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" preview url 3000

Report format:

• detected port(s)
• chosen port and reason
• final preview URL

Error Handling Matrix

Missing endpoint

Symptom:

• endpoint is required

Action:

• ask user for --endpoint or TCB_SANDBOX_ENDPOINT

Missing session for session-scoped command

Symptom:

• session-id is required

Action:

• ask user for --session-id or TCB_SANDBOX_SESSION_ID

401/403 class authorization errors

Action:

• verify session id value and gateway header mapping
• verify optional extra headers (TCB_SANDBOX_HEADERS_JSON) when custom gateway policies are enabled

408/timeout

Action:

• retry with larger --timeout
• split large tool actions into smaller steps

Tool call failure (HTTP problem details)

Action:

• surface detail exactly from RFC 9457 response
• propose one concrete retry strategy based on the failed tool

Output Contract

When running in automation context:

• prefer --output json
• include only structured fields required by downstream steps
• for failed requests, parse and forward error_code, retryable, retry_after, and owner_action_required

When running in interactive context:

• keep pretty output
• summarize key result and next step in plain language

Non-Goals

This skill does not:

• bypass TRW security boundaries
• persist long-term credentials outside session-scoped secret management
• guarantee behavior outside documented TRW endpoints