ic-star-tech Sandbox Executor Skill
Trigger
Use this skill when the task requires executing commands in an isolated sandbox environment, or when managing workspace files.
Capabilities
- Acquire and release sandbox leases from the Foundry sandbox pool
- Execute shell commands inside the sandbox container
- Write files to the sandbox workspace via API
- Monitor command output and detect success/failure
API Reference
Acquire a sandbox lease
POST {SANDBOX_DAEMON_URL}/acquire
Content-Type: application/json
x-sandbox-token: {token}
{"username": "<agent_username>"}
Returns: {"lease_id": "...", "slot": 1, ...}
Execute a command
POST {SANDBOX_DAEMON_URL}/leases/{lease_id}/terminal/exec
Content-Type: application/json
{"command": "<shell_command>"}
Returns: Terminal output
Write a file to workspace
PUT {SANDBOX_DAEMON_URL}/users/{username}/workspace/write
Content-Type: application/json
x-sandbox-token: {token}
{"path": "relative/path/to/file.txt", "content": "file content here"}
List workspace files
GET {SANDBOX_DAEMON_URL}/users/{username}/workspace/tree
x-sandbox-token: {token}
Release the sandbox
POST {SANDBOX_DAEMON_URL}/release
Content-Type: application/json
{"lease_id": "<lease_id>"}
Best Practices
- Always release the sandbox lease after use (even on error — use try/finally)
- Wait 3-5 seconds after sandbox acquisition for container initialization
- Use unique markers in commands to detect success:
echo EXIT_CODE=$? - Set reasonable timeouts for long-running commands:
timeout 30 <command> - Check pool status before acquiring:
GET /pool-status
Environment Variables
SANDBOX_DAEMON_URL: Daemon endpoint (default:http://localhost:9000)SANDBOX_TOKEN: Authentication token for the daemon API
Error Handling
- If lease acquisition fails, the pool may be full — retry after delay
- If command execution times out, the sandbox may need to be released and re-acquired
- Always check HTTP status codes: 200/201 = success, 4xx = client error, 5xx = server error