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
• 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:

npm install -g tcb-sandbox-cli@latest

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

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 --value-stdin for secrets set to avoid secret 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 set/delete), restate intent before execution.
5. For destructive actions, require explicit confirmation from the user.
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 Confirmation Template

Before running tools call bash or any secrets mutation/retrieval command, ask for explicit confirmation in this format:

Confirm high-risk action: <exact command intent>, target session=<session-id>, expected impact=<what changes>. Type "approve" to continue.

Proceed only after a clear affirmative response.

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

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"}'

Secrets

Set from stdin (preferred):

printf '%s' "<USER_APPROVED_SECRET_VALUE>" | tcb-sandbox \
  --endpoint "$TCB_SANDBOX_ENDPOINT" \
  --session-id "$TCB_SANDBOX_SESSION_ID" \
  secrets set TRW_SESSION_SECRET --value-stdin

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

Preview

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 from stdin (safe path, no plaintext in command history)
printf '%s' "<USER_APPROVED_SECRET_VALUE_V1>" | tcb-sandbox \
  --endpoint "$TCB_SANDBOX_ENDPOINT" \
  --session-id "$TCB_SANDBOX_SESSION_ID" \
  secrets set TRW_SESSION_SECRET --value-stdin

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

# 3) Optional: verify value retrieval only when user explicitly asks
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  secrets get TRW_SESSION_SECRET

# 4) Rotate to new value
printf '%s' "<USER_APPROVED_SECRET_VALUE_V2>" | tcb-sandbox \
  --endpoint "$TCB_SANDBOX_ENDPOINT" \
  --session-id "$TCB_SANDBOX_SESSION_ID" \
  secrets set TRW_SESSION_SECRET --value-stdin

# 5) Delete deprecated key
tcb-sandbox --endpoint "$TCB_SANDBOX_ENDPOINT" --session-id "$TCB_SANDBOX_SESSION_ID" \
  secrets delete 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":"npm 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":"npm 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 pre-release headers (TCB_SANDBOX_HEADERS_JSON)

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