Skip to main content
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.
The agent reuses the same VM for all steps of a task, so files on disk and installed packages persist between commands. If the VM is stopped or unreachable when the agent tries to use it again, the platform wakes it back up automatically and the agent continues — files and installed packages are preserved. Commands that were interrupted mid-run aren’t blindly retried; the agent sees the failure and decides what to do next.

​
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.
  • Browser automation — Playwright is pre-installed (Chromium + Google Chrome) via the vm-browser-automation skill, enabling stateful sessions, SPA scraping, form filling, and screenshot capture — no extra setup needed.
  • PDF generation — produce high-quality PDFs from Typst markup using the pre-installed Typst binary (vm-typst skill), alongside the existing pandoc/pypdf support.
  • Package installs — pip install, npm install, and apt-get work for any additional libraries you need.
  • 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.

​
Secrets

You can give the VM access to tokens — a GitHub PAT, an API key — without the agent ever seeing the real value. Create a Virtual Machine secret under Shared Assets → Secrets, then select it on the agent’s Virtual Machine capability. Every new VM gets that secret as an environment variable. Outbound HTTPS requests to the hosts you allow on the secret have the real value substituted into request headers; anywhere else, including the VM itself, only a placeholder is present. Three encodings cover the usual cases:
  • Header as-is — API tokens sent in Authorization: Bearer or a custom header.
  • Git / HTTP Basic Auth — the value is stored so the agent can send Authorization: Basic $VAR. Use this with git’s http.extraHeader, not a token in the URL.
  • GitHub PAT — one secret becomes two variables: the raw token for the GitHub API, plus a git-ready Basic Auth value. Default hosts are github.com and api.github.com.
See Credentials for how secrets are stored and scoped.

​
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 (pre-installed) and save the results to a CSV.”
  • “Convert this Typst template into a formatted PDF report with our Q1 metrics.”
Combine Virtual Machine with Send Email, Google Drive, or SharePoint to pick up files from a shared location, process them in the VM, and deliver results back — entirely on a schedule if you like.

Code Execution

Lightweight in-chat code execution for calculations and quick transformations

Documents

Store files produced or consumed by the VM as agent or chat documents

Scheduling

Run VM-based workflows automatically on a schedule