# Virtual computer ## Virtual Computer Virtual Computer (also known as Code Interpreter) gives your AI workers access to a real, internet-connected computer to execute complex tasks — batch operations, advanced math, data processing, and more. Toolhouse adds the virtual computer automatically when your worker needs it, or you can add it manually. ### How the virtual computer works You can create a worker that needs to perform tasks beyond simple text or API interactions. For example, you can build a data analyst worker that ingests a CSV file, runs statistical analysis, and returns a summary report. Rather than trying to perform these computations in memory, your worker can hand off the heavy lifting to the virtual computer. In these situations, Toolhouse can decide to give your worker access to the virtual computer. The worker will write code for it; the virtual computer will have a code interpreter sandbox that executes the code to perform actions needed to perform its tasks. Your worker interacts with the virtual computer by writing Python code and interpreting the results it returns. Any required Python packages are installed dynamically — your worker doesn't need to worry about environment setup. **Example prompt for Agent Editor:** > Make the worker download the CSV from this URL, calculate the 30-day rolling average for each numeric column, and return the results as a formatted table. ### Handing off tasks to the virtual computer Your worker decides autonomously when it's more efficient to delegate an operation to the virtual computer. You don't need to instruct it explicitly — but you can guide this behavior in the Agent Editor. To encourage your worker to use the virtual computer for specific types of tasks, tell the editor something like: > I want my worker to use code interpreter to execute its tasks. Make it optimize the code so it ran in parallel requests. You can use natural language and Toolhouse will translate it into proper instructions for your worker. **Example tasks well-suited for the virtual computer:** * Parsing and transforming large datasets * Running machine learning inference on uploaded files * Fetching and aggregating data from multiple web sources * Performing complex mathematical or statistical computations * Batch-renaming, converting, or compressing files ### Integrations inside the virtual computer The virtual computer has access to the same integrations as your worker. If your worker is connected to Google Drive, Slack, or a database, the virtual computer can interact with those services during its task execution — no extra configuration needed. ### Adding the virtual computer manually * Go to **Agents** in your Toolhouse dashboard * Click on your worker to edit it * Select **Integrations**, then click **Add Integration** * Choose **Virtual Computer** * Click **Save changes** ### Improving code quality with knowledge files By default, the worker writes its own Python code for the virtual computer and refines it autonomously. However, getting to a working solution can take multiple attempts — especially when the worker doesn't know the structure of your data, the shape of an API response, or the specifics of your environment. You can short-circuit this trial-and-error loop by supplying reference code directly through Agent Files. #### Why the worker may need multiple attempts The worker understands how the virtual computer works, but it can't always predict the format of the data you pass it. For example, if your CSV has unusual column names, nested JSON fields, or non-standard encodings, the worker may write code that fails on the first attempt, inspect the error, and revise. This is expected behavior — but it consumes execution credits and counts toward the four-minute limit. Providing a code reference eliminates most of this guesswork. #### Option 1: Provide a working code reference If you already have a Python script that handles your data correctly, you can give it to the worker as a starting point. * Drag and drop your `.py` file into the **Agent Files** section of the Agent Editor * Tell the editor to use it: > I gave a Python script to the worker that already handles our data pipeline correctly. Make the worker use it as a reference implementation when writing code for the virtual computer — don't make it start from scratch. The worker will read the file, understand the logic, and use it as a template when constructing code for the virtual computer. This is especially useful when your data has a non-obvious structure or when you need the worker to use a specific library or coding pattern consistently. #### Option 2: Reuse the last known good execution If you don't have a reference script but the worker eventually produced correct code after a few attempts, you can capture that successful run and feed it back in — so future executions skip straight to what works. * Go to [Logs](https://toolhouse.app/logs) and find the successful run * Click `code_interpreter` in **Traces** to view the generated code * Copy the code and save it as a `.py` file * Still in the Logs page for that worker, click on the **Agent ID** value to go back to the editor. * Select the **Details** tab, then drag your `.py` file into **Agent Files** * Go to the **Chat** tab and let the editor know: > I gave a Python script to the worker with the last working code interpreter execution. Make the worker use it as the reference implementation going forward so it won't have to rediscover the correct approach each time. On subsequent runs, the worker will reference this file instead of generating code from scratch, making executions faster and more reliable. #### When to use each approach | Situation | Recommended approach | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- | | You have existing, tested code, and the structure of your data does not change | Upload your own script as a reference | | The worker eventually got it right on its own, but your input data may change | Capture the successful execution and re-upload it | | Your data has a complex or unusual structure | Either approach; include a sample of the data alongside the script | | You have consistent inputs and need consistent outputs | Upload a reference that imports and uses those libraries explicitly | ### Security and isolation The virtual computer runs in a fully isolated environment. It cannot access your Toolhouse account data, and it cannot see or communicate with other workers. All code generated by your worker is reviewed before execution to ensure it is safe to run. Arbitrary shell commands are not permitted. **Each execution is ephemeral:** no state is persisted between sandboxes or sessions. If your worker needs to use the virtual computer more than once in a session, Toolhouse will provision two separate, independent sandboxes. ### Limitations and gotchas | Constraint | Detail | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | **Time limit** | Each task is limited to **four minutes** of execution time. | | **Early termination** | Based on resource constraints, the computer may terminate a task before the timeout. If this happens, no data is returned. | | **Retry on failure** | If a task terminates early, prompt your worker to retry. Example: *"The previous computation didn't complete — please try again."* | | **No arbitrary commands** | For security, only reviewed Python code can be executed. Shell commands and system calls are blocked. | | **No persistent state** | Each sandbox is ephemeral. Data is not carried over between executions or sessions. | | **Package availability** | Any Python package can be requested and will be installed dynamically at runtime, but installation time counts toward the one-minute limit. | ### Combining the virtual computer with other integrations Your worker can use its integrations within the virtual computer. The worker will automatically decide whether certain integrations are better called within the virtual computer, for example to parallelize operations. You can force your worker to pair the virtual computer with other integrations for end-to-end workflows. For instance: 1. **Google Drive integration** fetches a spreadsheet 2. **Virtual computer** cleans the data and runs a regression analysis 3. **Slack integration** posts the results to a channel To set this up, describe the full workflow in the Agent Editor: > Every Monday, make the worker last week's sales data from our Google Drive sheet, compute week-over-week growth per region, and send a summary to the #sales-updates Slack channel. I want the agent to perform these operations within the virtual computer for better performance. ### Connecting to third-party APIs The virtual computer can connect to any API on the internet — not just the integrations Toolhouse provides out of the box. If you need your worker to talk to a service Toolhouse doesn't natively support, you can teach it how by uploading the API's documentation directly in the Agent Editor. Because the virtual computer can install Python packages dynamically and make outbound HTTP requests, your worker can construct and execute API calls at runtime — no pre-built connector needed. #### How to set it up * Open your worker in **Agent Editor** * Tell the editor what you want, for example: > I want this worker to connect to a specific API. I'll give you a document with the instructions on how to connect. * Upload the API reference. Accepted formats: * **PDF** — ideal for legacy API documentation * **Plain text** — any `.txt` or `.md` file with endpoint descriptions, auth details, and example requests * **OpenAPI spec** — `.yaml` or `.json` files following the OpenAPI standard; the worker will parse the spec and use it to construct correct requests Your worker will read the documentation, understand the available endpoints and authentication method, and use the virtual computer to make the appropriate calls. ### Frequently asked questions **Can I see the Python code my worker generates?** Yes. Go to [Logs](https://toolhouse.app/logs), find your worker's name, then look at the code generated by clicking `code_interpreter` in **Traces.** **What happens if a required package takes too long to install?** Installation time counts toward the one-minute limit. If a package is large, the task may time out before execution begins. In that case, prompt your worker to retry or to use a lighter alternative package. **Is my data safe inside the virtual computer?** Yes. The sandbox is isolated and ephemeral — data processed inside the virtual computer is not stored after the task completes, and no other workers or users can access it. **What happens if the virtual computer takes too long to interpret the worker's code?** The code interpreter will send a timeout signal, and your worker can retry by writing more efficient code. **Can the virtual computer access the same tools as the worker?** Yes. The virtual computer has access to all the tools your worker can use. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.toolhouse.ai/toolhouse/capabilites/virtual-computer.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.