Skip to main content
Freestyle provides performant ephemeral VMs that are full linux systems. Freestyle is ideal when you want to give your AI a whole computer, not just run code snippets. This guide shows the full end-to-end flow: use the Mesa SDK outside the sandbox to set up resources, then use the Freestyle SDK to configure and mount Mesa inside the sandbox. The general flow for any sandbox integration is:
  1. Outside the sandbox — use the Mesa SDK (TypeScript or Python) to create repos, sign a short-lived access token, and orchestrate your workflow.
  2. Inside the sandbox — install the mesa CLI, configure it with a short-lived access token, and run mesa mount --daemonize to mount your repos as local directories.
  3. Run your agentcd into the mount path and launch your agent (e.g. Claude Code, Codex, or a custom agent). Any file edits are automatically persisted back to Mesa.
For details on FUSE setup, system dependencies, and container configuration, see POSIX Mount.

Setup

The example uses three environment variables:

Example Code

Freestyle sandboxes are Debian-based by default, so the standard Mesa install script works out of the box.

Tips

  • Mint the token outside the sandbox. Sign a short-lived, scoped access token from your API key outside the VM and pass only that token as MESA_API_KEY (alongside MESA_ORG). Your long-lived API key never crosses the sandbox boundary. See Authentication for details.
  • Install Mesa ahead of time when startup time matters. Installing at runtime is fine for a demo, but preinstalling Mesa and its dependencies makes VM startup faster and more predictable.
  • Always use --daemonize. This keeps Mesa mounted while your shell or agent continues to run.
  • Don’t forget user_allow_other. See POSIX Mount for the most common FUSE setup issue in sandbox environments.
  • Expect mount paths to depend on the VM user. In this example the VM runs as root, so Mesa mounts under /root/.local/share/mesa/mnt.