TCB Sandbox Skill

Operate and manage remote TRW workspace sandboxes via tcb-sandbox-cli for file, secret, shell, and preview tasks within secured sessions.

Security Scan

The skill's declared purpose, required credentials, CLI dependency, and runtime instructions are coherent for managing remote TRW sandboxes; there is one minor metadata inconsistency and inherent high-risk operations that the skill itself acknowledges and restricts.

Purpose & Capability

Name/description (manage TRW sandboxes) match what the skill requests: a tcb-sandbox CLI and session-bound endpoint/session-id. Requiring a session id as the primary credential is appropriate for session-scoped remote workspace operations.

Instruction Scope

SKILL.md contains explicit CLI commands to inspect files, run shells, manage secrets and previews — which is exactly the stated scope. These are inherently high-risk (remote bash, secrets handling) but the playbook includes confirmation templates and safe defaults (--value-stdin, redact headers). No instructions request unrelated local credentials. Note: README mentions an optional TCB_SANDBOX_HEADERS_JSON env var that is not listed in the registry's required env metadata.

Install Mechanism

Install spec is a public npm package (tcb-sandbox-cli@latest) that creates the tcb-sandbox binary. This is a typical and proportionate install mechanism for a CLI-based skill. No arbitrary downloads or personal servers are referenced in the install instructions.

Credentials

Required env vars are limited to TCB_SANDBOX_ENDPOINT and TCB_SANDBOX_SESSION_ID (session id is correctly marked as primary). These are proportional. Minor inconsistency: README documents an optional TCB_SANDBOX_HEADERS_JSON which is not declared in registry metadata; that should be declared or removed to avoid confusion about what the skill may read.

Persistence & Privilege

Skill is not always:true and does not request system-wide persistence. It instructs installing a global npm CLI if missing (user/system privilege required for -g installs), which is normal for adding a CLI but should be considered by the user.

Assessment

This skill appears to be what it says: a thin instruction layer around a tcb-sandbox CLI that operates on remote TRW sessions. Before installing or using it, verify the npm package and its publisher (tcb-sandbox-cli) on the npm registry, and confirm the CLI source/release is trustworthy. Treat TCB_SANDBOX_SESSION_ID as a sensitive credential — anyone with it plus the endpoint can act inside the remote workspace. Be cautious when granting global npm install privileges; prefer local or vetted installations. Note the skill enables remote shell and secret operations — follow the provided confirmation templates and only approve exact, expected commands. If you rely on the optional TCB_SANDBOX_HEADERS_JSON header feature, ask the publisher to declare it in the skill metadata so the agent's behavior is transparent.

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