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

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 [email protected]

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 tools call 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" tools list

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. tools call capability_list — discover ids. Add --param revealPaths=true when you need absolute paths for capability_register or to read skill files under packagePath.
2. tools call capability_describe --param id=<capability-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)
4. tools call capability_install ... — instruction only; nothing is installed server-side and the capability list does not change yet.
5. Run returned steps in the sandbox (usually bash).
6. tools call capability_register ... with final command / serverName+command / packagePath.
7. tools call capability_list again immediately after successful register — refresh what exists in the session so you do not “forget” the new capability.
8. 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:
9. List keys: tools call list_mcp_servers → available_mcp_servers.
10. Add: tools call add_mcp_servers (Cursor-style mcpServers, bare { "<name>": { command, ... } }, or serverName|name|server + command). Same server name already present = no overwrite (幂等).
11. Delete: tools call remove_mcp_servers with serverNames (array / JSON array string) or single serverName|name|server — response includes per_server, status, and updated available_mcp_servers. Built-in server names cloudbase / memory cannot be removed.
12. Update: remove_mcp_servers then add_mcp_servers with new command/args/env.
13. If your MCP client only exposes capability_* tools, use capability_register / capability_remove (kind=mcp) and read .mcporter/mcporter.json instead of add_mcp_servers / remove_mcp_servers / list_mcp_servers.
14. Execute using the route from describe
15. executionBy=capability + executionVia=capability_invoke → native only: tools call capability_invoke --data '{"id":"…","action":"…","parameters":{…}}'. Native ids: secrets-store, files-transfer, preview-service, pty-service, git-archive.
16. executionVia=bash → tools call bash with the indicated command.
17. executionVia=bash+mcporter → bash running mcporter call <server>.<tool> ....
18. 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" tools help read

Generic tool call

By key-value parameters:

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call read --param path=README.md

By raw JSON:

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call write --data '{"path":"hello.txt","content":"hello"}'

MCP server list / declarative add (mcporter)

# list configured MCP server names (available_mcp_servers)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call list_mcp_servers --data '{}'

# add one stdio MCP server (idempotent by name)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call add_mcp_servers --data '{"serverName":"my-mcp","command":"npx","args":["-y","@scope/mcp-server"]}'

# add multiple servers (Cursor / VS Code fragment shape)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call add_mcp_servers --data '{"mcpServers":{"url_fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}'

# remove by server name (returns updated available_mcp_servers)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call remove_mcp_servers --data '{"serverName":"my-mcp"}'

# remove multiple by name
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call remove_mcp_servers --data '{"serverNames":["srv-a","srv-b"]}'

Capability management

# list capabilities
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call capability_list

# describe one capability
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call capability_describe --param id=git-archive

# invoke capability action (preferred git archive path)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call capability_invoke --data '{"id":"git-archive","action":"push_snapshot","parameters":{"message":"snapshot"}}'

# legacy alias (still supported)
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call git_push --param message='snapshot'

Secrets (primary via top-level tools)

Set:

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

List keys:

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

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.

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  pty create --command bash --args -lc 'sleep 60'

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  pty send-input 12345 --text 'echo hellon'

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

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

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.

tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" preview ports
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" preview url 3000

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

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" 
  tools call capability_invoke --data '{"id":"secrets-store","action":"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" 
  tools call capability_invoke --data '{"id":"secrets-store","action":"list","parameters":{}}'

# 3) Optional: verify value retrieval only when user explicitly asks
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call capability_invoke --data '{"id":"secrets-store","action":"get","parameters":{"key":"TRW_SESSION_SECRET"}}'

# 4) Rotate to new value
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" 
  tools call capability_invoke --data '{"id":"secrets-store","action":"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" 
  tools call capability_invoke --data '{"id":"secrets-store","action":"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" 
  tools call bash --data '{"command":"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" 
  tools call bash --data '{"command":"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" 
  tools call read --param path=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" 
  tools call edit --data '{"path":"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" 
  tools call read --param path=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" 
  tools call bash --data '{"command":"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" 
  tools call bash --data '{"command":"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