Files and Repositories

Additional Files

Add files to the VM filesystem during creation:

import { freestyle } from "freestyle-sandboxes";

const { vm } = await freestyle.vms.create({
  additionalFiles: {
    "/app/config.json": {
      content: JSON.stringify({ apiKey: "secret" }),
    },
    "/etc/app/settings.conf": {
      content: "debug=true\nport=3000",
    },
  },
});

Binary Files

Use base64 encoding for binary files:

const { vm } = await freestyle.vms.create({
  additionalFiles: {
    "/app/image.png": {
      content: "iVBORw0KGgoAAAANSUhEUgA...", // Base64 encoded
      encoding: "base64",
    },
  },
});

Large Files

For large files, consider:

Using git repositories (see below)
Downloading during VM startup
Using external storage

const { vm } = await freestyle.vms.create({
  systemd: {
    services: [
      {
        name: "download-assets",
        mode: "oneshot",
        exec: ["curl -o /app/data.zip https://example.com/data.zip"],
        wantedBy: ["multi-user.target"],
      },
    ],
  },
});

Git Repositories

Clone git repositories into your VMs automatically during creation.

Basic Usage

First, create a repo reference, then use it when creating VMs:

import { freestyle } from "freestyle-sandboxes";

const { repoId } = await freestyle.git.repos.create({
  source: {
    url: "https://github.com/owner/repo",
  },
});

const { vm } = await freestyle.vms.create({
  gitRepos: [
    { repo: repoId, path: "/app" },
  ],
});

Multiple Repositories

Clone multiple repos into different paths:

const { vm } = await freestyle.vms.create({
  gitRepos: [
    { repo: frontendRepoId, path: "/app/frontend" },
    { repo: backendRepoId, path: "/app/backend" },
    { repo: sharedRepoId, path: "/app/shared" },
  ],
  workdir: "/app",
});

Specifying a Branch or Commit

Clone a specific revision:

const { vm } = await freestyle.vms.create({
  gitRepos: [
    {
      repo: repoId,
      path: "/app",
      rev: "main", // Branch, tag, or commit SHA
    },
  ],
});

With Systemd Services

A common pattern is to clone a repo and run services from it:

const { vm } = await freestyle.vms.create({
  gitRepos: [
    { repo: repoId, path: "/app" },
  ],
  workdir: "/app",
  systemd: {
    services: [
      {
        name: "install-deps",
        mode: "oneshot",
        exec: ["npm install"],
        workdir: "/app",
        after: ["freestyle-git-sync.service"], // Wait for repo to be cloned
        wantedBy: ["multi-user.target"],
      },
      {
        name: "web-server",
        mode: "service",
        exec: ["npm start"],
        workdir: "/app",
        after: ["install-deps.service"],
      },
    ],
  },
});

Using Specs

Put file and repo configuration in specs for reuse. Use them as snapshot layers for caching:

import { VmSpec } from "freestyle-sandboxes";

const spec = new VmSpec({
  gitRepos: [
    { repo: repoId, path: "/app" },
  ],
  additionalFiles: {
    "/app/.env.example": { content: "API_KEY=\nDATABASE_URL=" },
  },
  systemd: {
    services: [
      {
        name: "install-deps",
        mode: "oneshot",
        exec: ["npm install"],
        workdir: "/app",
        after: ["freestyle-git-sync.service"],
        wantedBy: ["multi-user.target"],
      },
    ],
  },
});

// Create a VM directly from the spec (no caching)
const { vm } = await freestyle.vms.create({ spec });

// Add environment-specific files on top
const { vm: prodVm } = await freestyle.vms.create({
  snapshot: spec,
  additionalFiles: {
    "/app/.env": { content: "API_KEY=prod-key\nDATABASE_URL=prod-db" },
  },
});