Choosing a runtime

Every way of running code on Boat is a sandbox: a Linux machine that stops on a timer with its disk saved. They differ in who starts the work, and who decides when the machine comes and goes.

Boat manages less as you decide more

Each runtime hands you more of the machine:

programSandbox + main

dev boxConnectSandbox

per taskCreateSandbox

your code

you

you

you

processes

Boat

you

you

start & stop

Boat

you

you

how many machines

Boat

Boat

you

From left to right, Boat manages less and you decide more. A program runs itself; a dev box is one machine you drive; per-task sandboxes are as many machines as your code creates.

Programs: your server at a URL

A Boat.Sandbox with a main runs your Effect program with Node.js. Each deploy that changes the code restarts it in the same sandbox, and its port answers at https://<subdomain>-3000.on.boat.dev.

src/Api.ts

import * as Boat from "@alchemy.run/boat";
import * as Effect from "effect/Effect";
import * as HttpServerResponse from "effect/http/HttpServerResponse";

export default class Api extends Boat.Sandbox<Api>()(
  "Api",
  { main: import.meta.url, public: true },
  Effect.gen(function* () {
    return { fetch: Effect.succeed(HttpServerResponse.text("hello")) };
  }),
) {}

A program sandbox never stops on its own. Choose it for an API or a service that needs a whole machine: Docker, a desktop, a long-lived process. See Programs.

restart

One sandbox serves every request, and keeps serving. A deploy that changes the code restarts the process in place.

A dev box: one machine you drive

A Boat.Sandbox without main is a machine the Stack keeps. A Worker reaches it with ConnectSandbox, runs commands in it, and resumes it when it has stopped.

const devBox = yield* Boat.ConnectSandbox(DevBox);
yield* devBox.resume({ autoStop: "30 minutes" });
yield* devBox.exec("git pull && npm test", { cwd: "/home/user/app" });

It stops after its autoStop with its disk saved, so you pay for it only while it works. Choose it for an agent’s home, a preview environment, or a build box. See Sandboxes.

stopped, disk saved

The dev box stops when its timer runs out and keeps its files. The next request resumes it.

Sandboxes per task: as many machines as you need

CreateSandbox gives a Worker or Function a client that creates sandboxes, from a snapshot when you bind one. Your code drives each one and deletes it when the task is done.

const sandboxes = yield* Boat.CreateSandbox(Golden);
const sandbox = yield* sandboxes.create({ type: "small", autoStop: "10 minutes" });
yield* sandbox.exec("npm test");
yield* sandbox.delete();

Choose it for agent loops, code a user sends, and anything that needs a fresh machine each time. See Sandboxes.

Each task gets a sandbox of its own, started from the same snapshot, and deleted when the task ends.

Mix runtimes in one app

One account runs all three at once. A Worker creates a sandbox per task from a snapshot, drives a dev box, and calls a program’s API:

ApiWorker

acmeaccount

Goldensnapshot

task-42sandbox per task

DevBoxdev box

Searchprogram

A Worker, Api, outside Boat creates task sandboxes from Golden, runs commands in DevBox, and calls the Search program at its URL. Each binding gets its own key.