# Virtual computer

## Virtual Computer

Virtual computer 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 this case, Toolhouse detects the worker will benefit from a dedicated compute environment and will attach a virtual computer to it.

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:

> Whenever you need to process files, run numerical computations, or perform batch operations, always use the virtual computer.

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

### 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 **one minute** 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. |

### Example: combining the virtual computer with other integrations

Your worker can 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, pull last week's sales data from our Google Drive sheet, compute week-over-week growth per region using the virtual computer, and send a summary to the #sales-updates Slack channel.

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


---

# 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=<question>
```

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.