Running tools

Every tool execution follows the same path: deploy → execute → stream logs → return result. You don't have to do any of this manually — the UI handles it — but it helps to know what's happening.

Deploy

The first time you run a tool (or the first time after you've edited it), the sandbox fetches a fresh copy:

1. The browser asks the sandbox to deploy tool T.
2. The sandbox calls the backend with its API token: GET /api/tools/T/archive.zip.
3. The backend verifies you own the tool and streams back a zip archive.
4. The sandbox extracts it to /sandbox/tools/T/, detects the language (Python or JavaScript), and installs dependencies (pip install -r requirements.txt or npm install).

Deployment typically takes a second or two; dependency‑heavy tools can take longer on first deploy.

Execute

Once deployed, the sandbox keeps a worker for that tool — a pre‑warmed process ready to receive input. When you click Run:

1. The browser sends the input and any settings to the sandbox over a WebSocket.
2. The sandbox hands the request to the tool's worker.
3. The worker calls the tool's process(input, settings) function.
4. The result comes back over the same WebSocket.

Because the worker is already alive, repeated runs of the same tool are fast — there's no cold start cost after the first execution.

Worker pool

Each sandbox keeps up to 20 workers alive simultaneously. Beyond that, the least‑recently‑used worker is evicted to make room. Workers also time out after ~15 minutes of idleness.

In practice you almost never need to think about this — the pool self‑manages. The main visible effect is that a tool you just ran will run again instantly, while a tool you haven't touched in a while may take a beat to warm up.

Logs

Anything your tool writes to stdout / stderr or logs through the SDK is streamed back in real time and displayed in the execution console. Log messages include a timestamp and severity level.

Logs are also kept for the duration of the execution so you can review them after the tool finishes.

Timeouts and limits

• Default timeout: 30 seconds per execution. Long‑running tools can request a higher timeout.
• Concurrent workers: 20 per sandbox.
• Tool worker idle timeout: 15 minutes.

If a tool exceeds the timeout, the worker is killed and you'll see a TimeoutError. A subsequent run starts a fresh worker automatically.

What if the sandbox is offline?

If your sandbox isn't running when you click Run, the UI shows the red / orange status and the execution is blocked. Start the sandbox and try again.

For cloud sandboxes that auto‑stopped, the UI will offer to start it for you.