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
.pyfile into the Agent Files section of the Agent EditorTell 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 and find the successful run
Click
code_interpreterin Traces to view the generated codeCopy the code and save it as a
.pyfileStill 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
.pyfile into Agent FilesGo 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
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
Time limit
Each task is limited to two hours 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:
Google Drive integration fetches a spreadsheet
Virtual computer cleans the data and runs a regression analysis
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
.txtor.mdfile with endpoint descriptions, auth details, and example requestsOpenAPI spec —
.yamlor.jsonfiles 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, 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.
Last updated