freestyle-sandboxes

Freestyle SDK

Learn more at docs.freestyle.sh

Installation

npm install freestyle-sandboxes

CLI Usage

The Freestyle SDK includes a command-line interface for managing your Freestyle resources.

Setup

Set the environment variable with your API key:

export FREESTYLE_API_KEY="your-api-key"

Or create a .env file in your project directory:

FREESTYLE_API_KEY=your-api-key

Commands

Virtual Machines

# Create a new VM
freestyle vm create --name my-vm

# Create a VM from a snapshot (for debugging)
freestyle vm create --snapshot <snapshot-id>

# Create a VM with domain
freestyle vm create --domain myapp.example.com --port 3000

# Create VM and SSH into it (auto-deletes on exit)
freestyle vm create --ssh

# Create VM from snapshot and SSH into it
freestyle vm create --snapshot <snapshot-id> --ssh

# List all VMs
freestyle vm list

# SSH into a VM
freestyle vm ssh <vmId>

# SSH into a VM and delete it on exit
freestyle vm ssh <vmId> --delete-on-exit

# Execute a command on a VM
freestyle vm exec <vmId> "ls -la"

# Delete a VM
freestyle vm delete <vmId>

Serverless Deployments

# Deploy from inline code
freestyle deploy --code "export default () => 'Hello World'"

# Deploy from a file
freestyle deploy --file ./my-function.js

# Deploy from a Git repository
freestyle deploy --repo <repoId>

# Add environment variables
freestyle deploy --code "..." --env API_KEY=secret --env DEBUG=true

Serverless Runs

# Execute a one-off function from inline code
freestyle run --code "console.log('Hello!')"

# Execute from a file
freestyle run --file ./script.js

Utilities

# Get help for any command
freestyle --help
freestyle vm --help

SDK Usage

import { freestyle } from "freestyle-sandboxes";

// Create and store code with git.
const { repoId } = await freestyle.git.repos.create({
  source: {
    url: "https://github.com/freestyle-sh/freestyle-base-nextjs-shadcn",
  },
});

// Create a new branch from the default branch
const repo = freestyle.git.repos.ref({ repoId });
const { name, sha } = await repo.branches.create({
  name: "feature/something",
});

// Create commits with files (text and binary)
const { commit } = await repo.commits.create({
  message: "Add new feature",
  branch: "feature/something",
  files: [
    { path: "README.md", content: "# My Project" },
    { path: "logo.png", content: base64Image, encoding: "base64" }
  ],
  author: { name: "John Doe", email: "[e-mail]" }
});

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

await vm.fs.writeTextFile("/repo/api/hello.js", "...");

// Deploy your code to the internet.
const { deploymentId } = await freestyle.serverless.deployments.create({
  repo: repoId,
});

// Verify a custom domain and point it at your deployment.
const { record } = await freestyle.domains.verifications.create({
  domain: "example.com",
});

console.log(record);

await freestyle.domains.verifications.complete({
  domain: "example.com",
});

await freestyle.domains.mappings.create({
  domain: "example.com",
  deploymentId: deploymentId,
});

// test your app with lightweight JS workers
for (let i = 0; i < 10; i++) {
  freestyle.serverless.runs.create({
    code: `export default () => {
        fetch("https://example.com/api/hello")
          .then(res => res.json()) 
        })
        `,
  });
}