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. 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

CODEBLOCK0

If command is missing, install CLI:

CODEBLOCK1

Then re-run:

CODEBLOCK2

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:

• - INLINECODE8
• INLINECODE9

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

• - INLINECODE10

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

CODEBLOCK3

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

Safety Rules

Always follow these rules:

1. 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:

INLINECODE26

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

CODEBLOCK4

If not ready, report readiness failure and stop.

2) Capability discovery

CODEBLOCK5

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:

CODEBLOCK6

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. 1. capability-list — discover ids. Add --reveal-paths when you need absolute paths for capability-register or to read skill files under packagePath.
2. INLINECODE36 — 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. 4. 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

CODEBLOCK7

Docs and tool discovery

CODEBLOCK8

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

CODEBLOCK9

Git Push

Push a workspace snapshot to a remote git repository.

CODEBLOCK10

Workspace Snapshot / Restore

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

CODEBLOCK11

Session mcporter (add / remove / list MCP servers)

CODEBLOCK12

Capability management

CODEBLOCK13

Secrets (primary via CLI subcommands)

Set:

CODEBLOCK14

Get (plaintext — only when user explicitly asks):

CODEBLOCK15

List keys (metadata only, no plaintext):

CODEBLOCK16

Delete:

CODEBLOCK17

Binary files

CODEBLOCK18

PTY

PTY subcommands call top-level PTY tools.

CODEBLOCK19

Preview

Preview subcommands call top-level preview tools.

CODEBLOCK20

Standard Tools Quick Map

Use this quick map to pick the right tool fast.

• - read: read a text file from workspace
• INLINECODE98: create or overwrite a text file
• INLINECODE99: apply targeted string-level edits to existing text
• INLINECODE100: search file content by pattern
• INLINECODE101: search files by name/path patterns
• INLINECODE102: inspect directory structure
• INLINECODE103: run shell commands in session workspace
• INLINECODE104: execute multiple tool calls with one request

INLINECODE105 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 INLINECODE115
• if task is structure discovery, use ls or INLINECODE117
• 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 INLINECODE120

Case Study: Secrets Lifecycle

Goal:

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

Commands:

CODEBLOCK21

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:

CODEBLOCK22

Troubleshooting hints:

• - no port found: check whether app started successfully and is listening on INLINECODE124
• 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:

CODEBLOCK23

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:

CODEBLOCK24

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:

CODEBLOCK25

Report format:

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

Error Handling Matrix

Missing endpoint

Symptom:

• - INLINECODE126

Action:

• - ask user for --endpoint or INLINECODE128

Missing session for session-scoped command

Symptom:

• - INLINECODE129

Action:

• - ask user for --session-id or INLINECODE131

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 INLINECODE133
• 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 INLINECODE135
• include only structured fields required by downstream steps
• for failed requests, parse and forward error_code, retryable, retry_after, and INLINECODE139

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