> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Freestyle Sandbox Provider

> Build a third-party Sandbox provider backed by Freestyle VMs.

# Freestyle Sandbox Provider

[Freestyle VMs](https://www.freestyle.sh/docs/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

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
<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>`.