bottleship 0.0.1 → 0.1.0-prototype.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+Add a section on top with a new version to release it: pushing it to main publishes that version to npm.
+Prerelease versions like `0.1.0-prototype.1` go to the dist-tag named after them (`prototype`), plain versions to `latest`.
+
+## 0.1.0-prototype.1
+
+- The last step of `bottleship init` opens your local agent (Claude Code, Codex, opencode or Cursor) to add bottleship to its global instructions, instead of showing text to copy.
+- `bottleship init --reset` starts over: sets the config aside as `config.json.bak` and asks everything again, and on a terminal offers to forget saved logins.
+- Fixed: a status check could read a box's state while it was being written and report a waiting login as running, or a finished agent as stopped.
+- Fixed: removing a box that was still waiting for its device login left the login process running.
+
+## 0.1.0-prototype.0
+
+First prototype. `bottleship init` sets up a provider and a coding agent once, then your local agent runs other agents in remote boxes with `new`, `status`, `ask`, `exec` and `rm`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Knauber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,188 @@
-# bottleship
+# bottleship (prototype)
 
-Reserved for Bottleship. Nothing here yet.
+A small CLI your local coding agent uses to run other coding agents in remote sandboxes ("boxes"), like subagents. Your agent writes the prompt, starts a box, checks on it, follows up, and cleans up. The agent in the box clones the repo, works, commits, pushes, and opens a PR.
+
+bottleship is stateless: no daemon, no local task list. The box id is the handle, and everything about a run lives in the box.
+
+This README is written for agents. Humans: run `bottleship init` once, then tell your agent to read this file.
+
+## Install
+
+```sh
+npm install -g <path or git URL of this package>   # will be `npm i -g bottleship` once published
+```
+
+Needs Node >= 22.18 on this machine. Installing from a git URL or a checkout builds the TypeScript sources (`npm install` runs `npm run build`).
+
+## Onboarding
+
+Once per machine, in a terminal:
+
+```sh
+bottleship init
+```
+
+It asks where boxes run (provider), which agent runs in them (`claude`, `codex`, `opencode`, `cursor`), how that agent logs in, and the git name and email for their commits, then collects the secrets boxes need and runs a live check: create a box, run a command, set up the agent, get one reply, destroy the box. Re-running it re-checks everything and only asks for what is missing.
+
+An agent can run it non-interactively; it never prompts and prints JSON:
+
+```sh
+bottleship init --yes --provider docker --agent claude --git-name "Ada Lovelace" --git-email ada@example.com
+```
+
+`--provider ssh` also needs `--host <host>`; `--provider custom --name <name>` sets up a custom provider (see below). `local` and `ssh` run agents with no isolation, so init needs the user's explicit OK: a confirm in the terminal, or `--i-understand-no-isolation`. Only pass that flag when the user said so.
+
+For an agent on the device login route (codex by default), the live check stops at the login with `login_needs_human`, since someone has to approve it in a browser. Ask the user to run `bottleship init` in their terminal.
+
+At the end, init opens the user's own agent on this machine (Claude Code, Codex, opencode or Cursor, whichever is installed) with a prompt to add the instructions below to its global instructions (for Cursor, a user rule file `~/.cursor/rules/bottleship.mdc`; Cursor documents that folder, not whether its CLI reads it), so the user only approves the change. With `--yes`, the JSON's `next` asks the calling agent to add `instructions` to its own global instructions file and show the user the change.
+
+Rerunning `bottleship init` only asks what is missing. `bottleship init --reset` starts over: it sets `~/.bottleship/config.json` aside as `config.json.bak` and asks everything again; on a terminal it also offers to forget the saved logins. With `--yes` it never deletes saved logins.
+
+If a secret is missing it fails with `secret_missing`. Then ask the user to run `bottleship init` in their own terminal, where it asks with a hidden prompt. Never ask the user to paste a secret to you.
+
+### Secrets
+
+Box env vars are configured under `env` in `~/.bottleship/config.json` (and per agent). A value is a plain string or a secret source:
+
+| Source | Meaning |
+|---|---|
+| `{ "store": "claude" }` | bottleship's store: macOS Keychain, or a 0600 file under `~/.bottleship/secrets` |
+| `{ "command": "gh auth token" }` | the output of a command on this machine |
+| `{ "env": "CORP_KEY" }` | an environment variable of the bottleship process |
+
+Defaults: `GH_TOKEN` (git pushes and `gh` both use it) from the store, plus the agent's login (below). Init asks for a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) limited to the repos boxes work on, with Contents and Pull requests read and write (Metadata read comes with them), so a box cannot touch the rest of the account. `gh auth token` (every repo the user can reach) is used only if the user picks it in init and confirms a warning. Either way, turn on branch protection for `main` so a box can only reach it through a reviewed PR.
+
+### Agent logins
+
+Each agent preset lists the login routes it offers (`login.routes`) and the one boxes use (`login.use`). Init asks on a first pick; pick another for one agent in `~/.bottleship/config.json`, e.g. `"agents": { "codex": { "login": { "use": "token" } } }`.
+
+- `token`: a long-lived token or API key in bottleship's store, set as an env var in every box.
+- `device`: the agent logs in inside each box. `new` (and `ask`, if the box's login expired) starts the login and returns its URL and code for the user to approve in a browser; the task starts once they do. Nothing is stored on this machine.
+- `none`: no login.
+
+| Agent | Routes (default first) | Why |
+|---|---|---|
+| `claude` | token: `CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token` | Anthropic's documented way to use a Claude subscription headless ([docs](https://code.claude.com/docs/en/authentication)). Boxes never get `ANTHROPIC_API_KEY` unless you configure it, as it would win over the token. |
+| `codex` | device: `codex login --device-auth` per box; token: `CODEX_API_KEY` (an OpenAI API key) | One ChatGPT login (`auth.json`) must not be shared across machines or parallel runs ([docs](https://learn.chatgpt.com/docs/auth/ci-cd-auth)), so each box logs in itself. Once, first: in ChatGPT, Settings, Security, turn on device code login for Codex. |
+| `cursor` (no reply tested yet) | token: `CURSOR_API_KEY` from https://cursor.com/dashboard/api (bills to your Cursor plan); device: `cursor-agent login` per box | API keys are Cursor's documented headless login ([docs](https://cursor.com/docs/cli/reference/authentication)). |
+| `opencode` | none: free models; device: a ChatGPT plan via `opencode auth login openai --method chatgpt-headless` per box; token: `OPENCODE_API_KEY` (OpenCode Zen), `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` | Per-box logins and provider API keys ([docs](https://opencode.ai/docs/)). Never a Claude subscription: Anthropic allows those only in Claude Code. |
+
+On `new`, the `.env*` files at the root of the current repo (not `*.example`, `*.sample`, `*.template`) are copied into the box workspace at the same paths.
+
+Real tokens are in the box, so the agent there can do anything those tokens allow: keep them narrow (a fine-grained `GH_TOKEN`, branch protection on `main`). A credential proxy that keeps them out of boxes is not built yet.
+
+## Providers
+
+Where boxes run. Pick one with `bottleship init` (or `--provider <name>`, and `new --provider <name>` per box):
+
+- `docker`: containers on this machine, from the box template (see Templates); without one, from `image` (default exeuntu).
+- `exe`: [exe.dev](https://exe.dev) VMs over ssh; needs `ssh exe.dev` working. No box template: exe.dev boots VMs only from registry images, so boxes install the agent at start.
+- `e2b` (untested): [e2b.dev](https://e2b.dev) cloud sandboxes; API key from https://e2b.dev/dashboard.
+- `daytona` (untested): [daytona.io](https://daytona.io) cloud sandboxes; API key from https://app.daytona.io/dashboard/keys.
+- `modal` (untested): [modal.com](https://modal.com) cloud sandboxes; token id and secret from `modal token new` or https://modal.com/settings/tokens.
+- `ssh` (untested on a real host): any machine you can `ssh` into without a password prompt; each box is a directory `~/bottleship-boxes/<id>` there, used as its `$HOME`. No isolation: agents run as that user with permission prompts off. Options: `host` (required, anything ssh accepts, e.g. a `~/.ssh/config` alias; `init --host`), `root`.
+- `local`: git worktrees on this machine. The box workspace is a `git worktree` of your local repo on branch `bottleship/<id>` (from your `HEAD` commit, without uncommitted changes); `rm` removes the worktree and keeps the branch. No isolation: agents run as you, with your files and logins, with permission prompts off. Boxes stop when the laptop sleeps.
+- `custom`: your company's sandboxes, see below.
+
+`local` and `ssh` need the user's OK in `bottleship init` (stored as `acceptNoIsolation` on the provider); without it `new` refuses them. `rm` there kills the box's processes: those marked with the box (`BOTTLESHIP_BOX`), and on macOS those in the box's process groups whose working directory is in the box.
+
+Provider API keys are read on this machine only and never reach a box; `bottleship init` asks for them.
+
+"Untested" means built from the provider's docs and SDK and type-checked, with live tests in `test/live/` that run when the provider's keys are set, but never run against the real service yet.
+
+## Custom providers
+
+For a company sandbox system with only an API or a CLI. A human runs `bottleship init` and picks `custom` (an agent: `bottleship init --yes --provider custom --name <name>`). That copies [presets/providers/http.example.ts](presets/providers/http.example.ts) to `~/.bottleship/providers/<name>.ts` and adds `"<name>": { "module": "providers/<name>.ts" }` under `providers` in `~/.bottleship/config.json`. Then, as the agent:
+
+1. Replace every TODO in `~/.bottleship/providers/<name>.ts` with the real API calls, or, if the system has a CLI, run its commands with `kit.run`. Find out how the system creates a sandbox, runs a command in it, and deletes it (its docs, its CLI's `--help`, or ask the user).
+2. Put the module's options in its config entry, with secrets as secret sources, never as plain values:
+
+```json
+"providers": {
+  "corp": { "module": "providers/corp.ts", "baseUrl": "https://sandboxes.corp.example/api", "apiKey": { "store": "corp-sandbox" } }
+}
+```
+
+3. Ask the user to run `bottleship init` in their terminal. It asks for missing secrets with a hidden prompt, then checks the provider end to end: create a box, run a command, set up the agent, get one reply, destroy the box. Fix what fails and run it again.
+
+The contract is `Provider` in [src/types.ts](src/types.ts): `create` (resolves once the box can run commands), `exec` (one-shot `bash -c`, with stdin), `destroy`, and optionally `status`, `openStream` (a binary-clean long-lived exec, for `exec -i`) and `template` (build or find a box template from a `TemplateSpec`, see Templates; `create` then gets its reference). Boxes must stay up until `rm`, since the agent runs in the background between calls. Node runs the `.ts` module directly, no build step. For a system whose CLI fits in shell templates, `"module": "builtin:command"` needs no code, see [presets/providers/command.ts](presets/providers/command.ts).
+
+## Usage
+
+Every command prints JSON; errors are `{ "error", "message", "fix" }` with exit code 1.
+
+```sh
+bottleship new "<task>" [--repo owner/name | --no-repo] [--provider P] [--agent A]
+# { "id": "docker:bs-fix-login-bug-3fa2", "provider": "docker", "agent": "claude", "repo": "acme/web", "next": "..." }
+# device login route: { "id", "provider", "agent", "repo", "login": { "url", "code"?, "agent" }, "next": "show the user this URL and code; ..." }
+
+bottleship status <id> [--wait 600] [--lines 40]
+# { "id", "box": "running", "agent": "running" | "exited" | "stopped", "exitCode"?, "log": "<last lines>", "next" }
+# { "id", "box": "running", "agent": "waiting_for_login", "login": { "url", "code"?, "agent" }, "log", "next" }
+# { "id", "box": "running", "agent": "login_failed", "exitCode", "log": "<the login's output>", "next" }
+# { "id", "box": "gone", "next" }
+
+bottleship ask <id> "<follow-up>"       # continues the same conversation; refused while the agent runs
+# { "id", "agent": "running", "next" }, or with an expired device login { "id", "agent": "waiting_for_login", "login", "next" }
+bottleship exec <id> -- git log --oneline -5
+bottleship exec <id> -- "npm test 2>&1 | tail -20"   # one argument is a script, several are argv
+bottleship exec -i <id> -- <cmd>        # streams stdin/stdout, e.g. for an IDE attaching over ACP
+bottleship rm <id>
+```
+
+`new` returns as soon as the agent has started, or, on the device route, once the login shows its URL: show the user the URL and code, and the task starts after they approve. A login nobody approves within 15 minutes fails (`login_failed`); `ask` then logs in again and, if the task never ran, runs the message as the task. The repo defaults to the current directory's `origin` (with the `local` provider, a worktree of this checkout). The box gets the env, the agent's login, the git identity, a git credential helper that uses `$GH_TOKEN`, and the agent's install commands; then the agent runs detached in `~/workspace` with your prompt.
+
+Agents are configured as shell templates (`{prompt}` is filled in shell-quoted):
+
+```json
+"agents": {
+  "claude": {
+    "install": ["command -v claude >/dev/null || npm install -g --silent @anthropic-ai/claude-code"],
+    "run": "claude -p {prompt} --dangerously-skip-permissions",
+    "resume": "claude -p {prompt} --continue --dangerously-skip-permissions",
+    "env": { "IS_SANDBOX": "1" },
+    "unset": ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+    "login": { "routes": ["token"], "use": "token", "token": { "env": "CLAUDE_CODE_OAUTH_TOKEN", "store": "claude", "command": "claude setup-token" } }
+  }
+}
+```
+
+`unset` drops env vars from the box unless you configure them. A device login is `"device": { "command", "status", "setup"?, "timeout"? }`: `command` prints a URL (and code) and exits 0 once approved, `status` exits 0 when the box is logged in. An entry for a builtin agent only needs the fields it changes. The presets are in [presets/agents](presets/agents).
+
+If a box has no Node, bottleship installs it into `~/.bottleship/node` without sudo.
+
+## Templates
+
+Boxes start from a prebuilt template when the provider supports one (`docker` builds a local image, `e2b` a template, `daytona` a snapshot, `modal` a named image; `exe`, `local`, `ssh` and custom ones have none). `bottleship init` builds it in the live check ("build the box template", minutes the first time) and records it under `templates.<provider>` in `~/.bottleship/config.json` as `{ "name", "ref" }`.
+
+The template is one Dockerfile: `node:22-bookworm-slim` with git, curl, ca-certificates, gh and ripgrep, a non-root user `box` (uid 1000, home `/home/box`) whose npm globals go to `~/.bottleship/npm`, plus the configured agent's `install` commands run as `box`. Its name is `bottleship-<hash of the Dockerfile>`, so changing the agent, its install commands or bottleship's Dockerfile makes a new one, built on the next `init`; a rerun with no changes finds the existing one. Templates never hold secrets or logins; those go into each box at start.
+
+Only the configured agent is baked in. `new --agent <other>` still uses the template and installs the other agent at start. When the recorded template does not match the current config, `new` starts the box without one (setup installs what it lacks, only slower) and says so in `warning`; run `bottleship init` to rebuild. Providers without `template()` (`local`, `ssh`, custom ones) set boxes up at start as before.
+
+## Instructions for your agent
+
+`bottleship init` prints this block; add it to your agent's global instructions (e.g. `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`).
+
+```md
+## Remote agents with bottleship
+
+You can run other coding agents in remote sandboxes ("boxes") with the `bottleship` CLI, like subagents. Every command prints JSON; errors carry a `fix`.
+
+- Start remote work with `bottleship new "<prompt>"` from inside the repo (or `--repo owner/name`). Write a complete prompt: the task, the context it needs, and what done means, including "work on branch <name>, commit and push as you go, and open a PR when done". The box agent sees nothing of this conversation.
+- Treat each box as a subagent you manage. `new` returns an id; keep track of your ids yourself, bottleship keeps no list.
+- If `new` or `ask` returns a `login`, show the user its URL and code; the box agent starts once they approve it in their browser.
+- `bottleship status <id>` shows whether the agent is still running and the tail of its output; `--wait <seconds>` blocks until it finishes.
+- `bottleship ask <id> "<follow-up>"` continues the same conversation once the agent has finished.
+- `bottleship exec <id> -- <cmd>` inspects the box (git log, test output, files).
+- `bottleship rm <id>` when the work is merged or abandoned. If a box is gone, start a new one on the pushed branch.
+- If the user wants to watch or steer a box from their IDE, find out how their IDE attaches to an agent over a command (ACP) and give it `bottleship exec -i <id> -- <the agent's ACP command>`.
+- Secrets: never ask the user to paste a secret to you. If bottleship reports one missing, ask them to run `bottleship init` in their terminal.
+```
+
+## Development
+
+```sh
+npm test                               # build, then all tests
+npx vitest run test/cli.test.ts        # one file (needs a build first)
+grep -rn 'ponytail:' src presets       # deliberate shortcuts and their upgrade paths
+```

package/bin/bottleship

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/src/cli.js";

package/dist/presets/providers/command.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderFactory } from "../../src/types.ts";
+declare const command: ProviderFactory;
+export default command;

package/dist/presets/providers/command.js

@@ -0,0 +1,39 @@
+// A provider driven by shell command templates, for sandboxes that have a CLI.
+// Values substituted into a template are shell-quoted: {script}, {id}.
+// {name!} inserts the raw value, for URLs and the like.
+//
+// options:
+//   create:   creates box {id}; may print JSON {"id": ...} or a bare id (else {id} is used)
+//   exec:     runs {script} with bash in box {id}; must pass stdin/stdout through
+//   stream:   (optional) like exec but kept open, binary-clean (no TTY); defaults to exec
+//   destroy:  removes box {id}
+//   status:   (optional) exits 0 if box {id} is running
+//
+// example:
+//   "corp": { "module": "builtin:command",
+//             "create": "corpbox create --name {id}",
+//             "exec": "corpbox ssh {id} -- bash -c {script}",
+//             "destroy": "corpbox rm {id}" }
+import { fill, run, spawnStream } from "./util.js";
+const command = ({ options }) => {
+    for (const k of ["create", "exec", "destroy"])
+        if (!options[k])
+            throw new Error(`command provider: missing "${k}" template`);
+    const sh = (tpl, values, opts) => run("sh", ["-c", fill(tpl, values)], opts);
+    return {
+        async create({ id }) {
+            const out = (await sh(options.create, { id })).stdout.trim();
+            try {
+                return { id: JSON.parse(out).id ?? id };
+            }
+            catch {
+                return { id: out && !/\s/.test(out) ? out : id };
+            }
+        },
+        exec: (id, script, { stdin } = {}) => sh(options.exec, { id, script }, { stdin, check: false }),
+        openStream: (id, script) => spawnStream("sh", ["-c", fill(options.stream ?? options.exec, { id, script })]),
+        ...(options.status && { status: async (id) => ((await sh(options.status, { id }, { check: false })).code === 0 ? "running" : "gone") }),
+        destroy: (id) => sh(options.destroy, { id }, { check: false }),
+    };
+};
+export default command;

package/dist/presets/providers/daytona.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderFactory } from "../../src/types.ts";
+declare const daytona: ProviderFactory;
+export default daytona;

package/dist/presets/providers/daytona.js

@@ -0,0 +1,173 @@
+// Daytona sandboxes through @daytonaio/sdk. A box is a sandbox; its id is the sandbox id.
+//
+// options: {
+//   apiKey (secret source, e.g. { "store": "daytona" }), apiUrl?, target? (region),
+//   snapshot? (default: Daytona's default snapshot, user "daytona" with bash, git, curl and a writable $HOME),
+//   image? (any registry image instead of a snapshot; it needs bash, git, curl, base64 and a writable $HOME),
+//   autoStopMinutes? (default 0 = never)
+// }
+//
+// template() builds a Daytona snapshot from the Dockerfile, in the organization's default region or `target`; COPY from a local context does not work since spec Dockerfiles have none.
+import { randomBytes } from "node:crypto";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PassThrough, Writable } from "node:stream";
+import { shq } from "./util.js";
+const GONE = new Set(["destroyed", "destroying", "error", "build_failed"]);
+const RESTARTABLE = new Set(["stopped", "archived", "paused"]);
+const hex = () => randomBytes(6).toString("hex");
+const SNAPSHOT_BUSY = new Set(["pending", "building", "pulling", "snapshotting", "removing"]);
+const daytona = async ({ options, secret, log }) => {
+    if (!options.apiKey)
+        throw new Error('daytona needs an apiKey option, e.g. "apiKey": { "store": "daytona" }');
+    // loaded here so other providers never pay for the SDK
+    const { Daytona, DaytonaNotFoundError, Image } = await import("@daytonaio/sdk");
+    const client = new Daytona({ apiKey: secret(options.apiKey), apiUrl: options.apiUrl, target: options.target });
+    // ponytail: never auto-stops, because Daytona counts a running agent as idle and would stop it mid-task; idle boxes bill until `bottleship rm`. Set autoStopMinutes to cap that, a stopped box restarts on the next exec but its agent is gone
+    const autoStopInterval = options.autoStopMinutes ?? 0;
+    const cache = new Map();
+    const lookup = async (id) => {
+        try {
+            const sb = await client.get(id);
+            cache.set(id, sb);
+            return sb;
+        }
+        catch (e) {
+            if (e instanceof DaytonaNotFoundError)
+                return undefined;
+            throw e;
+        }
+    };
+    // a sandbox that can run commands, started again if it was stopped or archived
+    async function started(id) {
+        const cached = cache.get(id);
+        if (cached?.state === "started")
+            return cached;
+        const sb = await lookup(id);
+        if (!sb || GONE.has(sb.state ?? ""))
+            throw new Error(`daytona sandbox ${id} is gone`);
+        if (RESTARTABLE.has(sb.state ?? ""))
+            await sb.start(600);
+        else
+            await sb.waitUntilStarted(600);
+        return sb;
+    }
+    // drops the cached sandbox on failure, so the next call looks its state up again
+    async function withBox(id, fn) {
+        try {
+            return await fn(await started(id));
+        }
+        catch (e) {
+            cache.delete(id);
+            throw e;
+        }
+    }
+    // the snapshot's state, or undefined once there is none by that name
+    const snapshotState = (name) => client.snapshot.get(name).then((s) => s.state, (e) => {
+        if (e instanceof DaytonaNotFoundError)
+            return undefined;
+        throw e;
+    });
+    // ponytail: a snapshot another init is still building is polled for at most 30 minutes; raise it if agent installs get that slow
+    async function settled(name) {
+        for (let i = 0; i < 900; i++) {
+            const state = await snapshotState(name);
+            if (!state || !SNAPSHOT_BUSY.has(state))
+                return state;
+            await new Promise((res) => setTimeout(res, 2000));
+        }
+        throw new Error(`daytona snapshot ${name} is still not active after 30 minutes`);
+    }
+    return {
+        // snapshots belong to the organization, so a name cannot resolve to another organization's snapshot
+        async template({ name, dockerfile }) {
+            let state = await settled(name);
+            // Daytona deactivates a snapshot after 2 weeks without use
+            if (state === "inactive") {
+                await client.snapshot.activate(name);
+                state = await settled(name);
+            }
+            if (state === "active")
+                return name;
+            // a failed build keeps its name taken, so it goes before the rebuild
+            if (state) {
+                await client.snapshot.delete(name);
+                await settled(name);
+            }
+            // the SDK reads a Dockerfile only from disk
+            const dir = mkdtempSync(join(tmpdir(), "bottleship-daytona-"));
+            try {
+                writeFileSync(join(dir, "Dockerfile"), dockerfile);
+                await client.snapshot.create({ name, image: Image.fromDockerfile(join(dir, "Dockerfile")) }, { onLogs: (l) => log(l) });
+            }
+            finally {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            return name;
+        },
+        async create({ id, template }) {
+            const base = { name: id, labels: { bottleship: "1" }, autoStopInterval };
+            const sb = options.image && !template
+                ? await client.create({ ...base, image: options.image }, { timeout: 600 })
+                : await client.create({ ...base, snapshot: template ?? options.snapshot }, { timeout: 300 });
+            cache.set(sb.id, sb);
+            return { id: sb.id };
+        },
+        // the one-shot API merges stdout and stderr and takes no stdin, so stdin goes up as a file and both outputs come back base64'd
+        exec: (id, script, { stdin } = {}) => withBox(id, async (sb) => {
+            // a fresh 0700 dir, since stdin carries secrets (env.sh) and output may too
+            const d = `/tmp/bottleship-${hex()}`;
+            if (stdin !== undefined) {
+                await sb.fs.createFolder(d, "700");
+                await sb.fs.uploadFile(Buffer.from(stdin), `${d}/in`);
+            }
+            const r = await sb.process.executeCommand(`${stdin !== undefined ? "" : `mkdir -m 700 ${d} || exit 1; `}bash -c ${shq(script)} < ${stdin !== undefined ? `${d}/in` : "/dev/null"} > ${d}/out 2> ${d}/err; echo $?; base64 < ${d}/out | tr -d '\\n'; echo; base64 < ${d}/err | tr -d '\\n'; echo; rm -rf ${d}`);
+            const [code, out, err] = r.result.split("\n");
+            if (r.exitCode !== 0 || !/^\d+$/.test(code ?? ""))
+                throw new Error(`daytona exec in ${id} failed (exit ${r.exitCode}): ${r.result.slice(-500)}`);
+            return { code: Number(code), stdout: Buffer.from(out ?? "", "base64").toString(), stderr: Buffer.from(err ?? "", "base64").toString() };
+        }),
+        // a session command: stdin goes as base64 lines decoded in the box, so it stays binary-clean and "." ends it
+        // ponytail: Daytona relays output line by line as UTF-8 text, so a partial line shows once it ends and binary output is mangled; a PTY or a raw socket would fix that
+        openStream: (id, script) => withBox(id, async (sb) => {
+            const session = `bottleship-${hex()}`;
+            await sb.process.createSession(session);
+            const wrapper = `exec 3< <(while IFS= read -r l; do [ "$l" = . ] && break; printf %s "$l" | base64 -d; done)
+bash -c ${shq(script)} <&3; c=$?; kill $! 2>/dev/null; exit $c`;
+            const { cmdId } = await sb.process.executeSessionCommand(session, { command: `bash -c ${shq(wrapper)}`, runAsync: true, suppressInputEcho: true });
+            const send = (line) => sb.process.sendSessionCommandInput(session, cmdId, line).catch(() => { });
+            const stdout = new PassThrough();
+            const stderr = new PassThrough();
+            const closers = [];
+            const end = () => sb.process.deleteSession(session).catch(() => { });
+            const stdin = new Writable({
+                write: (chunk, _enc, cb) => void send(chunk.toString("base64") + "\n").then(() => cb()),
+                final: (cb) => void send(".\n").then(() => cb()),
+            });
+            sb.process
+                .getSessionCommandLogs(session, cmdId, (s) => stdout.write(s), (s) => stderr.write(s))
+                .catch(() => { })
+                .then(() => sb.process.getSessionCommand(session, cmdId).then((c) => c.exitCode ?? null, () => null))
+                .then((code) => {
+                stdout.end();
+                stderr.end();
+                closers.forEach((cb) => cb(code));
+                void end();
+            });
+            return { stdin, stdout, stderr, close: () => void end(), onClose: (cb) => closers.push(cb) };
+        }),
+        // a stopped or archived sandbox still counts as running, since exec starts it again
+        async status(id) {
+            const sb = await lookup(id);
+            return sb && !GONE.has(sb.state ?? "") ? "running" : "gone";
+        },
+        async destroy(id) {
+            const sb = await lookup(id);
+            cache.delete(id);
+            if (sb && !GONE.has(sb.state ?? ""))
+                await sb.delete(120);
+        },
+    };
+};
+export default daytona;

package/dist/presets/providers/docker.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderFactory } from "../../src/types.ts";
+declare const docker: ProviderFactory;
+export default docker;

package/dist/presets/providers/docker.js

@@ -0,0 +1,31 @@
+// Local Docker as a provider. Boxes are containers that live until `bottleship rm`.
+// The template is a local image tagged with its spec name, running as its own non-root user box.
+//
+// options: { image? (used without a template; default exeuntu, a dev image with git, curl and a non-root user), user? }
+import { run, spawnStream } from "./util.js";
+const docker = ({ options }) => {
+    const image = options.image ?? "ghcr.io/boldsoftware/exeuntu:latest";
+    const user = options.user ?? (image.includes("exeuntu") ? "exedev" : undefined);
+    // execs run as the container's user, set at create
+    const execArgs = (id, script) => ["exec", "-i", id, "bash", "-c", script];
+    return {
+        async template({ name, dockerfile }) {
+            if ((await run("docker", ["image", "inspect", name], { check: false })).code !== 0)
+                await run("docker", ["build", "-q", "-t", name, "-"], { stdin: dockerfile });
+            return name;
+        },
+        async create({ id, template }) {
+            const from = template ? [template] : [...(user ? ["--user", user] : []), image];
+            await run("docker", ["run", "-d", "--name", id, "--label", "bottleship=1", "--entrypoint", "sleep", ...from, "infinity"]);
+            return { id };
+        },
+        exec: (id, script, { stdin } = {}) => run("docker", execArgs(id, script), { stdin, check: false }),
+        openStream: (id, script) => spawnStream("docker", execArgs(id, script)),
+        async status(id) {
+            const r = await run("docker", ["inspect", "-f", "{{.State.Running}}", id], { check: false });
+            return r.code === 0 && r.stdout.trim() === "true" ? "running" : "gone";
+        },
+        destroy: (id) => run("docker", ["rm", "-f", id], { check: false }),
+    };
+};
+export default docker;

package/dist/presets/providers/e2b.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderFactory } from "../../src/types.ts";
+declare const e2b: ProviderFactory;
+export default e2b;

package/dist/presets/providers/e2b.js

@@ -0,0 +1,124 @@
+// E2B: Firecracker sandboxes over the e2b SDK. The default "base" template is Debian with bash, git, curl,
+// node and gh, run as a user with a writable $HOME.
+//
+// template() builds an E2B template from the Dockerfile; the E2B builder ignores SHELL, and COPY or ADD from a local context does not work since spec Dockerfiles have none.
+//
+// options: { apiKey? (secret source, else E2B_API_KEY), template? (default "base"), timeoutMinutes? (default 60) }
+import { PassThrough, Writable } from "node:stream";
+const e2b = async ({ options, secret, log }) => {
+    const { Sandbox, Template, ApiClient, ConnectionConfig, CommandExitError, NotFoundError } = await import("e2b");
+    const apiKey = options.apiKey ? secret(options.apiKey) : undefined;
+    // ponytail: a box dies this long after bottleship last touched it, and E2B caps a box's whole life at 1h (Hobby) or 24h (Pro); pause/resume lifecycle if agents run longer
+    const timeoutMs = (options.timeoutMinutes ?? 60) * 60_000;
+    // connecting also extends the box's timeout, so every exec and status keeps a box someone checks on alive
+    const boxes = new Map();
+    async function box(id) {
+        const hit = boxes.get(id);
+        if (hit && Date.now() - hit.at < 60_000)
+            return hit.sbx;
+        const sbx = await Sandbox.connect(id, { apiKey, timeoutMs });
+        boxes.set(id, { sbx, at: Date.now() });
+        return sbx;
+    }
+    const result = (r) => ({ code: r.exitCode, stdout: r.stdout, stderr: r.stderr });
+    // a non-zero exit is a result, not an error
+    const settle = (p) => p.then(result, (e) => {
+        if (e instanceof CommandExitError)
+            return result(e);
+        throw e;
+    });
+    // the id of this team's template named name with a finished build; a bare name can also resolve to another team's public template, so names are never handed to create
+    async function ownTemplate(name) {
+        const { api } = new ApiClient(new ConnectionConfig({ apiKey }));
+        let nextToken;
+        do {
+            const res = await api.GET("/v2/templates", { params: { query: { limit: 100, nextToken } } });
+            if (!res.data)
+                throw new Error(`e2b could not list templates: ${res.response.status} ${JSON.stringify(res.error)}`);
+            const hit = res.data.find((t) => !t.isDefault && t.buildStatus === "ready" && t.names.some((n) => n === name || n.endsWith(`/${name}`)));
+            if (hit)
+                return hit.templateID;
+            nextToken = res.response.headers.get("X-Next-Token") || undefined;
+        } while (nextToken);
+    }
+    return {
+        // ponytail: two inits racing on one name both build, E2B keeps the later build; fine since both come from the same Dockerfile
+        async template({ name, dockerfile }) {
+            const found = await ownTemplate(name);
+            if (found)
+                return found;
+            const built = await Template.build(Template().fromDockerfile(dockerfile), name, { apiKey, onBuildLogs: (e) => log(String(e)) });
+            return built.templateId;
+        },
+        // the bottleship id goes into metadata; E2B picks the sandbox id
+        async create({ id, template }) {
+            const sbx = await Sandbox.create(template ?? options.template ?? "base", { apiKey, timeoutMs, metadata: { bottleship: id } });
+            await sbx.commands.run("true");
+            boxes.set(sbx.sandboxId, { sbx, at: Date.now() });
+            return { id: sbx.sandboxId };
+        },
+        // the SDK runs `bash -l -c <script>`; timeoutMs 0 lifts its 60 second command limit
+        async exec(id, script, { stdin } = {}) {
+            const sbx = await box(id);
+            if (stdin === undefined)
+                return settle(sbx.commands.run(script, { timeoutMs: 0 }));
+            const h = await sbx.commands.run(script, { background: true, stdin: true, timeoutMs: 0 });
+            if (stdin.length)
+                await h.sendStdin(stdin);
+            await h.closeStdin();
+            return settle(h.wait());
+        },
+        // ponytail: the SDK hands output over as UTF-8 text, so binary stdout gets mangled; fine for text protocols
+        async openStream(id, script) {
+            const sbx = await box(id);
+            const stdout = new PassThrough();
+            const stderr = new PassThrough();
+            const h = await sbx.commands.run(script, {
+                background: true,
+                stdin: true,
+                timeoutMs: 0,
+                onStdout: (d) => void stdout.write(d),
+                onStderr: (d) => void stderr.write(d),
+            });
+            let code;
+            const closers = [];
+            const done = h.wait().then((r) => r.exitCode, (e) => (e instanceof CommandExitError ? e.exitCode : null));
+            void done.then((c) => {
+                code = c;
+                stdout.end();
+                stderr.end();
+                closers.splice(0).forEach((cb) => cb(c));
+            });
+            // Writable runs one write at a time, so stdin arrives in order
+            const stdin = new Writable({
+                write: (chunk, _enc, cb) => void h.sendStdin(chunk).then(() => cb(), cb),
+                final: (cb) => void h.closeStdin().then(() => cb(), cb),
+            });
+            stdin.on("error", () => { });
+            return {
+                stdin,
+                stdout,
+                stderr,
+                close: () => void h.kill().catch(() => { }),
+                onClose: (cb) => (code === undefined ? closers.push(cb) : cb(code)),
+            };
+        },
+        async status(id) {
+            boxes.delete(id);
+            try {
+                await box(id);
+                return "running";
+            }
+            catch (e) {
+                if (e instanceof NotFoundError)
+                    return "gone";
+                throw e;
+            }
+        },
+        async destroy(id) {
+            boxes.delete(id);
+            return Sandbox.kill(id, { apiKey });
+        },
+    };
+};
+export default e2b;

package/dist/presets/providers/exe.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderFactory } from "../../src/types.ts";
+declare const exe: ProviderFactory;
+export default exe;