Virtual Machine

The Virtual Machine capability gives your agent an ephemeral Linux environment with bash, Python, and Node.js pre-installed. It’s ideal for anything that needs a real shell — running scripts, installing packages, processing files, and generating Office documents — without the limits of the in-chat code execution sandbox.

​

How it works

When the agent needs to run something, it spins up a fresh virtual machine, runs the commands, and destroys it when done. The VM is isolated from the platform and the internet calls it makes originate from the VM itself, not your workspace. A typical flow:

1. Create a virtual machine (create_vm).
2. Run bash commands inside it (execute_bash) — Python, Node, shell, package installs, and long-running jobs are all fair game.
3. Transfer files in and out as needed — the agent can upload files you attached to the chat, or files stored as agent documents, and download results back into the chat.
4. Destroy the VM when the task is complete (destroy_vm). Idle VMs also auto-stop on their own.

The agent reuses the same VM for all steps of a task, so files on disk and installed packages persist between commands.

​

When to use it

Virtual Machine is the right tool when the agent needs a real Linux environment. Common cases:

• Office documents — create and edit .xlsx, .pptx, .docx, and .pdf files using libraries like openpyxl, python-pptx, python-docx, pypdf, and pandoc.
• Data processing — crunch large CSV, JSON, or Parquet files with pandas, or run anything that needs more than a short in-chat script.
• Package installs — pip install, npm install, apt-get, and headless browser drivers (e.g. Playwright) work as expected.
• Longer-running jobs — multi-step pipelines, batch conversions, or commands that would exceed the in-chat code execution timeout.

For quick one-off calculations or data transformations, the lighter-weight Code Execution capability is usually a better fit — it runs inline in the chat with no VM startup cost.

​

File transfers

The agent can move files in both directions between the chat and the VM:

• Upload — attach a file to the chat (or point the agent at an agent document) and the agent uploads it into the VM for processing.
• Download — after the VM produces output, the agent pulls the file back and saves it as a chat document or agent document that you can open or share.

Transfers are streamed, so file size is limited only by the VM’s disk, not by a separate upload cap.

​

Example use cases

• “Take this sales spreadsheet, pivot the numbers by region and month, and give me back a new .xlsx with charts.”
• “Convert these ten Word documents to clean Markdown and save each one as an agent document.”
• “Fill in this PowerPoint template with the metrics from our database and email the deck to the leadership team.”
• “Run this Python script against orders.csv and report the top 20 customers by revenue.”
• “Scrape the pricing pages of these competitors using Playwright and save the results to a CSV.”

​

Related features