Skip to main content

​
Freestyle Sandbox Provider

Freestyle VMs are extremely powerful sandboxes with nested virtualization, full networking, and the ability to scale to more resources than alternatives. Use Freestyle VMs when you want to give your agents a real computer, not a code runner. The workflow sets no hardcoded runtime. Instead it passes a SandboxProvider object to <Sandbox provider={freestyleProvider}>, so the same workflow code runs on any VM backend.

​
Provider shape

import { freestyle } from "freestyle";
import { createFreestyleSandboxProvider } from "./provider.js";

const freestyleProvider = createFreestyleSandboxProvider({
  freestyle,
  command: "node /workspace/run-smithers-sandbox.js",
  idleTimeoutSeconds: 60,
  setupFiles: {
    "/workspace/run-smithers-sandbox.js": {
      content: `
        const fs = require("node:fs");
        const req = JSON.parse(fs.readFileSync("/workspace/smithers-request.json", "utf8"));
        fs.writeFileSync("/workspace/smithers-result.json", JSON.stringify({
          status: "finished",
          output: { summary: "handled " + req.input.prompt },
          runId: "freestyle:" + req.sandboxId
        }));
      `,
    },
  },
});

​
Workflow

<Workflow name="freestyle-provider-example">
  <Sandbox
    id="remote-edit"
    provider={freestyleProvider}
    workflow={remoteChildWorkflow}
    input={{ prompt: ctx.input.prompt }}
    output={outputs.sandboxResult}
    reviewDiffs={false}
    retries={0}
  />
</Workflow>

​
Why this shape

Freestyle VM creation, file APIs, and command execution map cleanly to the Smithers provider contract: Smithers creates the request bundle, the provider writes any setup files and the request JSON with vm.fs.writeTextFile(), the VM command runs with vm.exec(), the provider reads smithers-result.json with vm.fs.readTextFile(), and Smithers validates/applies the result bundle. Return a diffBundle (a Smithers diff-bundle object) from the provider for file changes, and Smithers will surface them through the same review-and-apply path used by <Sandbox reviewDiffs>.