tdsk-sandbox

Documents the pluggable sandbox execution layer with local and Kubernetes providers.

Updated Jan 4, 2026
One-click install
npx skills add https://github.com/threadedstack/threadedstack --skill tdsk-sandbox-threadedstack
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: tdsk-sandbox
Source: https://github.com/threadedstack/threadedstack/tree/main/.claude/skills/tdsk-sandbox
Command: npx skills add https://github.com/threadedstack/threadedstack --skill tdsk-sandbox-threadedstack

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developers working on the Threaded Stack codebase need to understand how the sandbox execution layer isolates and runs agent-generated code across local V8 isolates and Kubernetes pods without reading all 42 source files. ## Core Features & Use Cases - Architecture Reference: Explains the factory pattern behind createSandboxProvider, the ISandboxProvider interface, and both Local and Kube provider implementations. - Component Deep Dives: Covers KubeClient pod operations, IsolateRunner with 14 Node.js shims, virtual git with 22 subcommands via isomorphic-git, and pod manifest generation. - Use Case: When adding a new sandbox provider or debugging why evaluate() fails in a Kubernetes pod, consult this knowledge base to locate the right module, understand the security model, and follow established patterns like graceful degradation and lazy initialization. ## Quick Start Ask the AI to explain how the sandbox provider factory works or how to add a new sandbox provider type to the execution layer.

Frequently Asked Questions about tdsk-sandbox

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a sandbox provider in TypeScript?▼

Call createSandboxProvider(type) with a TSandboxType value to get a LocalSandboxProvider or KubeSandboxProvider instance. The factory is map-based and extensible via providers.set() for custom implementations of ISandboxProvider.

What is the difference between local and Kubernetes sandbox providers?▼

The local provider uses a just-bash virtual shell, in-memory filesystem, optional V8 isolate, and virtual git. The Kubernetes provider connects to existing pods via the K8s Exec API over WebSocket, never using child_process.

Does the local sandbox work without isolated-vm installed?▼

Yes, the local provider degrades gracefully when isolated-vm is unavailable. Shell, filesystem, and git operations still function; only V8 isolate-based code evaluation is affected.

How do I run code safely inside a V8 isolate?▼

Use IsolateRunner's evaluate(code, timeout) method, which lazily initializes the isolate and enforces a memory limit and timer clamp. It provides 14 Node.js shims including fs, path, buffer, and crypto, and process.exit() throws instead of exiting.

Why does the Kubernetes watcher restart every 10 minutes?▼

The cycleListen method restarts the watch every 10 minutes to work around Kubernetes bug #596, where long-lived watch connections silently stop delivering events. Pod events are wired to hydration via setupKubeWatcher.