Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

feat: add the agent37 sandbox backend

Vishnu6b694b026f20
diff --git a/adrs/agent37-sandbox-backend.md b/adrs/agent37-sandbox-backend.md
new file mode 100644
index 000000000..c46b84720
--- /dev/null
+++ b/adrs/agent37-sandbox-backend.md
@@ -0,0 +1,21 @@
+# Agent37 as an agent-computer backend
+
+Vishnu from Agent37 here. You asked whether we could host qm. The honest answer is that the part of qm that wants hosting is the agent computer, so this is a fifth sandbox backend, next to Sprites, smolmachines, Porter and AWS.
+
+Agent37 rents isolated Linux machines over a small REST API: create, exec, start, stop, delete. Each one keeps its disk, goes to sleep when idle, and comes back when the next command arrives. That is the lifecycle your Sprites and smolmachines backends already assume, so the mapping is direct: one Agent37 instance per qm scope, created on first use, named after the scope so an operator can recognise it in their Agent37 dashboard, deleted when qm tears the scope down.
+
+What the PR adds
+
+- `SANDBOX_BACKEND=agent37` with `AGENT37_API_KEY`. Optional knobs: `AGENT37_API_BASE_URL`, `AGENT37_NAME_PREFIX`, `AGENT37_TEMPLATE`, `AGENT37_CPUS`, `AGENT37_MEMORY_GB`, `AGENT37_DISK_GB`, `AGENT37_EGRESS_PROXY_URL`, and the shared `SANDBOX_TIMEOUT_SEC`.
+- `src/sandbox/agent37-sandbox.ts`, modeled on the smolmachines backend. Provision creates the instance and waits for it to run. Run is our exec endpoint. Teardown with destroy deletes the instance. Files move over the same exec endpoint in base64 chunks, the way the Porter backend does it, because our API has no separate file transfer. Process sessions, home backup, ro layers and blob staging come from the shared exec helpers unchanged.
+- Exec on our side returns within 280 seconds and caps each stream at 512 KiB. Longer commands run detached and are polled; larger output is spooled to disk and read back in chunks, so the agent never sees a truncated result.
+- A command sent to a sleeping instance starts it first, then runs. That is a retry inside the backend, not a heartbeat; the provider decides when a machine sleeps.
+- Profile: `writablePersistence: "resident_disk"`, `processSessions: true`, `egressEnforcement: "none"`. Our sandboxes reach the public internet and nothing private, but there is no per-domain allowlist, so the backend declares none rather than pretend.
+
+What it does not do
+
+- No idle reaping and no snapshot to the workspace. The disk is the machine's own and survives sleep, stop and start.
+- No image plumbing. The default template, `agent37-qm-computer`, is built from your `sandbox-base` image and published on our side, so the tools qm expects are the tools it gets. A different Agent37 template can be named with `AGENT37_TEMPLATE`.
+- No new CLI target. `qm init` still deploys the core to Fly, AWS or Porter; this only changes where the computers live.
+
+Tests run against an in-process fake of our API, so CI needs no Agent37 account. We would rather this live upstream than in a fork, and we will keep it green as the sandbox contract moves.
diff --git a/cli/src/secrets.ts b/cli/src/secrets.ts
index 1522ea68a..0e019dce1 100644
--- a/cli/src/secrets.ts
+++ b/cli/src/secrets.ts
@@ -156,6 +156,13 @@ export const FIRST_PARTY_SECRET_SPECS: readonly SecretSpec[] = [
description: "smolmachines API key for the agent-computer substrate.",
generate: "create an API key in the smolmachines console (https://smolmachines.com/console)",
},
+ {
+ name: "AGENT37_API_KEY",
+ service: "core",
+ required: { when: { kind: "env-equals", service: "core", name: "SANDBOX_BACKEND", value: "agent37" } },
+ description: "Agent37 API key for the agent-computer substrate.",
+ generate: "mint a key in the Agent37 dashboard (https://agent37.com/dashboard/cloud/api-keys)",
+ },
{
name: "DATABASE_URL",
service: "core",
diff --git a/scripts/dev/cli.ts b/scripts/dev/cli.ts
index 370a6da7c..2d1d18b31 100644
--- a/scripts/dev/cli.ts
+++ b/scripts/dev/cli.ts
@@ -245,7 +245,7 @@ async function bootOnSlot(slot: string, worktree: string, branch: string): Promi
branch,
callerEnv,
watch: !opts["no-watch"] && callerEnv.DEV_INSTANCE_WATCH !== "0",
- sandbox: opts.sandbox as "local" | "sprites" | "smolmachines" | "porter" | "auto",
+ sandbox: opts.sandbox as "local" | "sprites" | "smolmachines" | "porter" | "agent37" | "auto",
canaryChannel,
strict: opts.strict,
slack: withSlack,
@@ -644,7 +644,7 @@ async function main(): Promise<number> {
return await runDoctor({ json: opts.json, fix: opts.fix, store, slack: withSlack });
default:
console.error(
- "usage: dev [up|down|status|restart|canary|logs|doctor] [--json] [--force] [--rotate] [--strict] [--sandbox local|sprites|smolmachines|porter|auto] [--no-slack] [--no-watch] [--org id] [--fix]",
+ "usage: dev [up|down|status|restart|canary|logs|doctor] [--json] [--force] [--rotate] [--strict] [--sandbox local|sprites|smolmachines|porter|agent37|auto] [--no-slack] [--no-watch] [--org id] [--fix]",
);
return EXIT.usage;
}
diff --git a/scripts/dev/lib/sandbox.ts b/scripts/dev/lib/sandbox.ts
index 6ed2abed5..6104a2352 100644
--- a/scripts/dev/lib/sandbox.ts
+++ b/scripts/dev/lib/sandbox.ts
@@ -7,7 +7,7 @@ import { ensureDockerDaemon } from "./postgres.ts";
import { bestEffortValue, sleep } from "./util.ts";
export interface SandboxResolution {
- backend: "local" | "sprites" | "smolmachines" | "porter";
+ backend: "local" | "sprites" | "smolmachines" | "porter" | "agent37";
env: Record<string, string>;
detail: string;
publicApiUrl: string | null;
@@ -24,7 +24,7 @@ async function localImagePresent(image: string): Promise<boolean> {
export async function resolveSandbox(opts: {
worktree: string;
- requested: "local" | "sprites" | "smolmachines" | "porter" | "auto";
+ requested: "local" | "sprites" | "smolmachines" | "porter" | "agent37" | "auto";
corePort: number;
lock: string;
baseEnv: Record<string, string>;
@@ -99,6 +99,36 @@ export async function resolveSandbox(opts: {
};
}
+ if (backend === "agent37") {
+ const apiKey = opts.baseEnv.AGENT37_API_KEY;
+ if (!apiKey)
+ throw new Error(
+ "--sandbox agent37 requires AGENT37_API_KEY in the environment (mint one at https://agent37.com/dashboard/cloud/api-keys)",
+ );
+ let apiUrl = opts.baseEnv.PUBLIC_API_URL || null;
+ if (!apiUrl) {
+ apiUrl = await startQuickTunnel(opts.corePort, opts.lock, opts.log);
+ if (!apiUrl)
+ warnings.push(
+ "cloudflared tunnel didn't come up -- agent self-API (crons/sends) won't be reachable from the sandbox",
+ );
+ }
+ const env: Record<string, string> = {
+ SANDBOX_BACKEND: "agent37",
+ AGENT37_API_KEY: apiKey,
+ AGENT37_NAME_PREFIX: opts.baseEnv.AGENT37_NAME_PREFIX || "qmdev",
+ };
+ if (opts.baseEnv.AGENT37_API_BASE_URL) env.AGENT37_API_BASE_URL = opts.baseEnv.AGENT37_API_BASE_URL;
+ if (opts.baseEnv.AGENT37_TEMPLATE) env.AGENT37_TEMPLATE = opts.baseEnv.AGENT37_TEMPLATE;
+ if (opts.baseEnv.AGENT37_EGRESS_PROXY_URL) env.AGENT37_EGRESS_PROXY_URL = opts.baseEnv.AGENT37_EGRESS_PROXY_URL;
+ else
+ warnings.push(
+ "AGENT37_EGRESS_PROXY_URL unset -- agent37 sandbox runs with NO egress enforcement; set it to QA the forced-proxy path",
+ );
+ if (apiUrl) env.PUBLIC_API_URL = apiUrl;
+ return { backend: "agent37", env, detail: "Agent37 (api.agent37.com)", publicApiUrl: apiUrl, warnings };
+ }
+
if (backend === "porter") {
const porterToken = opts.baseEnv.PORTER_DEPLOY_API_TOKEN;
const projectId = opts.baseEnv.PORTER_DEPLOY_PROJECT_ID;
diff --git a/scripts/dev/lib/types.ts b/scripts/dev/lib/types.ts
index a64f9e2cf..5e28c7a0c 100644
--- a/scripts/dev/lib/types.ts
+++ b/scripts/dev/lib/types.ts
@@ -108,7 +108,7 @@ export interface BootSpec {
branch: string;
callerEnv: Record<string, string>;
watch: boolean;
- sandbox: "local" | "sprites" | "smolmachines" | "porter" | "auto";
+ sandbox: "local" | "sprites" | "smolmachines" | "porter" | "agent37" | "auto";
canaryChannel?: string;
strict: boolean;
slack?: boolean;
diff --git a/src/config.ts b/src/config.ts
index 4d32ae961..5f0800ba4 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -37,8 +37,8 @@ export interface Config {
databaseCaCertFile?: string;
harness: "mock" | "pi" | "opencode" | "codex" | "claude";
securityPosture: SecurityPosture;
- sandboxBackend: "aws" | "local" | "sprites" | "smolmachines" | "porter";
- sandboxSecondaryBackend?: "aws" | "local" | "sprites" | "smolmachines" | "porter";
+ sandboxBackend: "aws" | "local" | "sprites" | "smolmachines" | "porter" | "agent37";
+ sandboxSecondaryBackend?: "aws" | "local" | "sprites" | "smolmachines" | "porter" | "agent37";
deployProvider: "docker" | "aws" | "fly" | "porter";
egressServiceHosts?: string[];
brandingDefault?: OrgBranding;
@@ -159,6 +159,7 @@ export interface Config {
localSandbox: LocalSandboxEnv;
spritesSandbox: SpritesSandboxEnv;
smolmachinesSandbox: SmolmachinesSandboxEnv;
+ agent37Sandbox: Agent37SandboxEnv;
porterSandbox: PorterSandboxEnv;
porterDeploy: PorterDeployEnv;
awsDeploy: AwsDeployEnv;
@@ -432,6 +433,40 @@ function smolmachinesSandboxEnv(env: NodeJS.ProcessEnv): SmolmachinesSandboxEnv
};
}
+interface Agent37SandboxEnv {
+ apiKey?: string;
+ baseUrl?: string;
+ namePrefix?: string;
+ template?: string;
+ cpus?: number;
+ memoryGb?: number;
+ diskGb?: number;
+ egressProxyUrl?: string;
+ defaultTimeoutSec?: number;
+}
+
+function agent37SandboxEnv(env: NodeJS.ProcessEnv): Agent37SandboxEnv {
+ return {
+ ...(env.AGENT37_API_KEY ? { apiKey: env.AGENT37_API_KEY } : {}),
+ ...(env.AGENT37_API_BASE_URL ? { baseUrl: env.AGENT37_API_BASE_URL } : {}),
+ ...(env.AGENT37_NAME_PREFIX ? { namePrefix: env.AGENT37_NAME_PREFIX } : {}),
+ ...(env.AGENT37_TEMPLATE ? { template: env.AGENT37_TEMPLATE } : {}),
+ ...(numEnvStrict("AGENT37_CPUS", env.AGENT37_CPUS) !== undefined
+ ? { cpus: numEnvStrict("AGENT37_CPUS", env.AGENT37_CPUS) }
+ : {}),
+ ...(numEnvStrict("AGENT37_MEMORY_GB", env.AGENT37_MEMORY_GB) !== undefined
+ ? { memoryGb: numEnvStrict("AGENT37_MEMORY_GB", env.AGENT37_MEMORY_GB) }
+ : {}),
+ ...(numEnvStrict("AGENT37_DISK_GB", env.AGENT37_DISK_GB) !== undefined
+ ? { diskGb: numEnvStrict("AGENT37_DISK_GB", env.AGENT37_DISK_GB) }
+ : {}),
+ ...(env.AGENT37_EGRESS_PROXY_URL ? { egressProxyUrl: env.AGENT37_EGRESS_PROXY_URL } : {}),
+ ...(numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) !== undefined
+ ? { defaultTimeoutSec: numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) }
+ : {}),
+ };
+}
+
interface AwsDeployEnv {
region: string;
profile?: string;
@@ -700,11 +735,12 @@ function sandboxBackendEnvStrict(value: string | undefined, name = "SANDBOX_BACK
backend === "local" ||
backend === "sprites" ||
backend === "smolmachines" ||
- backend === "porter"
+ backend === "porter" ||
+ backend === "agent37"
)
return backend;
throw new Error(
- `${name}=${JSON.stringify(value)} is not recognized — use aws, local, sprites, smolmachines, or porter, or unset it.`,
+ `${name}=${JSON.stringify(value)} is not recognized — use aws, local, sprites, smolmachines, porter, or agent37, or unset it.`,
);
}
@@ -849,7 +885,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
}
if (env.NODE_ENV === "production" && !env.SANDBOX_BACKEND?.trim()) {
throw new Error(
- "SANDBOX_BACKEND must be set explicitly in production — use sprites, smolmachines, porter, aws, or local.",
+ "SANDBOX_BACKEND must be set explicitly in production — use sprites, smolmachines, porter, agent37, aws, or local.",
);
}
const sandboxBackend = sandboxBackendEnvStrict(env.SANDBOX_BACKEND);
@@ -1163,6 +1199,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
localSandbox: localSandboxEnv(env),
spritesSandbox: spritesSandboxEnv(env),
smolmachinesSandbox: smolmachinesSandboxEnv(env),
+ agent37Sandbox: agent37SandboxEnv(env),
porterSandbox: porterSandboxEnv(env),
porterDeploy: porterDeployEnv(env),
awsDeploy: {
diff --git a/src/deployment/secret-schema.ts b/src/deployment/secret-schema.ts
index 4c18f9b7f..b8d201900 100644
--- a/src/deployment/secret-schema.ts
+++ b/src/deployment/secret-schema.ts
@@ -7,6 +7,7 @@ type SecretGate =
| "sprites"
| "smolmachines"
| "porter"
+ | "agent37"
| "porter-deploy"
| "fly-sandbox"
| "fly-deploy"
@@ -37,6 +38,7 @@ export const CORE_SECRET_SPECS: readonly RuntimeSecretSpec[] = [
{ name: "DATABASE_URL", requiredWhen: "postgres" },
{ name: "SPRITES_TOKEN", requiredWhen: "sprites" },
{ name: "SMOLMACHINES_TOKEN", requiredWhen: "smolmachines" },
+ { name: "AGENT37_API_KEY", requiredWhen: "agent37" },
{ name: "PORTER_DEPLOY_API_TOKEN", requiredWhen: ["porter", "porter-deploy"] },
{ name: "FLY_API_TOKEN", requiredWhen: "fly-sandbox" },
{ name: "FLY_DEPLOY_API_TOKEN", requiredWhen: "fly-deploy" },
@@ -53,6 +55,7 @@ const GATE_PREDICATES: Readonly<Record<SecretGate, (env: NodeJS.ProcessEnv) => b
sprites: (env) => env.SANDBOX_BACKEND === "sprites" || env.SANDBOX_SECONDARY_BACKEND === "sprites",
smolmachines: (env) => env.SANDBOX_BACKEND === "smolmachines" || env.SANDBOX_SECONDARY_BACKEND === "smolmachines",
porter: (env) => env.SANDBOX_BACKEND === "porter" || env.SANDBOX_SECONDARY_BACKEND === "porter",
+ agent37: (env) => env.SANDBOX_BACKEND === "agent37" || env.SANDBOX_SECONDARY_BACKEND === "agent37",
"porter-deploy": (env) => env.DEPLOY_PROVIDER === "porter",
"fly-sandbox": (env) => env.SANDBOX_BACKEND === "fly",
"fly-deploy": (env) => env.DEPLOY_PROVIDER === "fly",
diff --git a/src/sandbox/agent37-sandbox.ts b/src/sandbox/agent37-sandbox.ts
new file mode 100644
index 000000000..7673b2d2e
--- /dev/null
+++ b/src/sandbox/agent37-sandbox.ts
@@ -0,0 +1,600 @@
+import { randomUUID } from "node:crypto";
+import type { WorkspaceLayer } from "../types.ts";
+import type { WorkspaceStore } from "../workspace/workspace-store.ts";
+import { createKeyedQueue, sleep } from "../util/async.ts";
+import { swallowAs, errMessage } from "../util/errors.ts";
+import { shq } from "../util/shell.ts";
+import { nonInteractiveShellPrefix } from "./sandbox-env.ts";
+import { createExecProcessSessions, type ExecProcessIo } from "./exec-process-session.ts";
+import { materializeRoLayers } from "./ro-layers.ts";
+import {
+ BLOB_TRANSFER_TTL_MS,
+ createExecBackup,
+ createExecBlobStaging,
+ createExecFileOps,
+ posixJoin,
+} from "./exec-file-ops.ts";
+import {
+ ephemeralCredLinkScript,
+ ephemeralCredLinkPaths,
+ type CredentialPathSpec,
+} from "../credentials/resident-paths.ts";
+import { DROPPED_PROXY_ENV, forceThroughProxyEnv, proxyExportPrefix } from "./sandbox-env.ts";
+import { BLOB_TRANSFER_AUD, mintCapabilityToken } from "../auth/capability-token.ts";
+import type { BlobTransferStore } from "../persistence/blob-transfer.ts";
+import { CAPABILITY_HEADER } from "../api/contract.ts";
+import { killableScript, killScript } from "./exec-kill.ts";
+import { visibleNotInstalled, visibleTools } from "./sandbox.ts";
+import { spriteScopeName } from "./sprites-sandbox.ts";
+import type {
+ AgentComputerProfile,
+ ExecOptions,
+ ExecResult,
+ ProvisionOptions,
+ Sandbox,
+ SandboxHandle,
+ TeardownOptions,
+} from "./sandbox.ts";
+
+const HOME_DIR = "/home/node";
+const WORKSPACE_BASENAME = "workspace";
+const RO_LAYERS_TAR = ".ro-layers.tar";
+const RO_LAYERS_MANIFEST = ".ro-layers.manifest";
+const INLINE_LIMIT = 128 * 1024;
+const READ_CHUNK = 256 * 1024;
+const WRITE_CHUNK_B64 = 64 * 1024;
+const MISSING_RC = 44;
+const EXEC_SYNC_MAX_SEC = 240;
+const EXEC_POLL_MS = 2_000;
+const EXIT_GRACE_MS = 60_000;
+const CREATE_TIMEOUT_MS = 330_000;
+const READY_TIMEOUT_MS = 180_000;
+const READY_POLL_MS = 2_000;
+const DEFAULT_AGENT37_BASE_URL = "https://api.agent37.com";
+const DEFAULT_TEMPLATE = "agent37-qm-computer";
+const DEFAULT_CPUS = 2;
+const DEFAULT_MEMORY_GB = 4;
+const DEFAULT_DISK_GB = 8;
+const STARTABLE_STATES = new Set(["stopped", "sleeping"]);
+const DEAD_STATES = new Set(["failed", "deleting", "deleted"]);
+
+interface InstanceInfo {
+ id: string;
+ name?: string | null;
+ status: string;
+}
+
+interface InstanceExecResponse {
+ exit_code: number;
+ stdout: string;
+ stderr: string;
+ truncated: boolean;
+}
+
+export interface Agent37SandboxOptions {
+ apiKey?: string;
+ baseUrl?: string;
+ namePrefix?: string;
+ template?: string;
+ cpus?: number;
+ memoryGb?: number;
+ diskGb?: number;
+ defaultTimeoutSec?: number;
+ egressProxyUrl?: string;
+ blobTransfer?: BlobTransferStore;
+ signingSecret?: string;
+ capabilitySecret?: string;
+ apiBaseUrl?: string;
+ extraTools?: string[];
+ credentialPaths?: CredentialPathSpec[];
+ fetchImpl?: typeof fetch;
+ onError?: (e: { category: string; code: string; message: string; scopeLabel?: string }) => void;
+}
+
+export function createAgent37Sandbox(workspace: WorkspaceStore, opts: Agent37SandboxOptions = {}): Sandbox {
+ if (!opts.apiKey && !opts.fetchImpl) throw new Error("SANDBOX_BACKEND=agent37 requires AGENT37_API_KEY");
+ const fetchImpl = opts.fetchImpl ?? fetch;
+ const baseUrl = (opts.baseUrl ?? DEFAULT_AGENT37_BASE_URL).replace(/\/+$/, "");
+ const prefix = opts.namePrefix ?? "qm";
+ const template = opts.template ?? DEFAULT_TEMPLATE;
+ const resources = {
+ cpu: opts.cpus ?? DEFAULT_CPUS,
+ memory: opts.memoryGb ?? DEFAULT_MEMORY_GB,
+ disk: opts.diskGb ?? DEFAULT_DISK_GB,
+ };
+ const defaultTimeoutSec = opts.defaultTimeoutSec ?? 600;
+ const workspaceDir = `${HOME_DIR}/${WORKSPACE_BASENAME}`;
+ const provisionQueue = createKeyedQueue<string>();
+
+ const idByName = new Map<string, string>();
+ const scopeByName = new Map<string, string>();
+ const scratchKeyByName = new Map<string, string>();
+ const activeScratch = new Map<string, number>();
+
+ async function api(method: string, path: string, body?: unknown, timeoutMs = 60_000): Promise<Response> {
+ return fetchImpl(`${baseUrl}${path}`, {
+ method,
+ headers: {
+ authorization: `Bearer ${opts.apiKey ?? ""}`,
+ ...(body !== undefined ? { "content-type": "application/json" } : {}),
+ },
+ ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+ signal: AbortSignal.timeout(timeoutMs),
+ });
+ }
+
+ async function apiJson<T>(method: string, path: string, body?: unknown, timeoutMs = 60_000): Promise<T> {
+ const res = await api(method, path, body, timeoutMs);
+ if (!res.ok) {
+ throw new Error(`agent37 ${method} ${path}: http ${res.status} ${(await res.text()).slice(0, 200)}`);
+ }
+ return (await res.json()) as T;
+ }
+
+ async function findInstance(name: string): Promise<InstanceInfo | null> {
+ const { data } = await apiJson<{ data: InstanceInfo[] }>("GET", "/v1/instances");
+ return data.find((i) => i.name === name && !DEAD_STATES.has(i.status)) ?? null;
+ }
+
+ async function awaitRunning(id: string): Promise<void> {
+ const deadline = Date.now() + READY_TIMEOUT_MS;
+ for (;;) {
+ const info = await apiJson<InstanceInfo>("GET", `/v1/instances/${encodeURIComponent(id)}`);
+ if (info.status === "running") return;
+ if (DEAD_STATES.has(info.status)) throw new Error(`agent37 instance ${id}: ${info.status}`);
+ if (Date.now() > deadline)
+ throw new Error(`agent37 instance ${id}: not running after ${READY_TIMEOUT_MS}ms (status=${info.status})`);
+ await sleep(READY_POLL_MS);
+ }
+ }
+
+ async function ensureRunning(id: string): Promise<void> {
+ const info = await apiJson<InstanceInfo>("GET", `/v1/instances/${encodeURIComponent(id)}`);
+ if (info.status === "running") return;
+ if (STARTABLE_STATES.has(info.status)) {
+ const res = await api("POST", `/v1/instances/${encodeURIComponent(id)}/start`, undefined, 120_000);
+ if (!res.ok && res.status !== 400) {
+ throw new Error(`agent37 start ${id}: http ${res.status} ${(await res.text()).slice(0, 200)}`);
+ }
+ }
+ await awaitRunning(id);
+ }
+
+ async function createInstance(name: string): Promise<InstanceInfo> {
+ const info = await apiJson<InstanceInfo>(
+ "POST",
+ "/v1/instances",
+ { template, name, resources, auto_sleep: true },
+ CREATE_TIMEOUT_MS,
+ );
+ await awaitRunning(info.id);
+ return info;
+ }
+
+ async function instanceIdFor(name: string): Promise<string> {
+ const cached = idByName.get(name);
+ if (cached) return cached;
+ const found = await findInstance(name);
+ if (!found) throw new Error(`agent37 instance ${name}: not found`);
+ idByName.set(name, found.id);
+ return found.id;
+ }
+
+ async function deleteInstance(name: string): Promise<void> {
+ const found = idByName.get(name) ?? (await findInstance(name))?.id;
+ idByName.delete(name);
+ if (!found) return;
+ const res = await api("DELETE", `/v1/instances/${encodeURIComponent(found)}`, undefined, 120_000);
+ if (!res.ok && res.status !== 404) {
+ throw new Error(`agent37 delete ${name}: http ${res.status} ${(await res.text()).slice(0, 200)}`);
+ }
+ }
+
+ async function postExec(name: string, script: string, timeoutSec: number): Promise<InstanceExecResponse> {
+ const id = await instanceIdFor(name);
+ const body = { command: script };
+ const timeoutMs = timeoutSec * 1000 + 2 * EXIT_GRACE_MS;
+ const first = await api("POST", `/v1/instances/${encodeURIComponent(id)}/exec`, body, timeoutMs);
+ let res = first;
+ if (!first.ok) {
+ const detail = (await first.text()).slice(0, 200);
+ if (first.status === 404) idByName.delete(name);
+ const notRunning = first.status === 400 && /running instances/i.test(detail);
+ if (first.status !== 404 && !notRunning) {
+ throw new Error(`agent37 exec ${name}: http ${first.status} ${detail}`);
+ }
+ const retryId = await instanceIdFor(name);
+ await ensureRunning(retryId);
+ res = await api("POST", `/v1/instances/${encodeURIComponent(retryId)}/exec`, body, timeoutMs);
+ if (!res.ok) {
+ throw new Error(`agent37 exec ${name}: http ${res.status} ${(await res.text()).slice(0, 200)}`);
+ }
+ }
+ const parsed = (await res.json()) as InstanceExecResponse;
+ if (parsed.truncated) {
+ throw new Error(`agent37 exec ${name}: output truncated by the API: chunk the read instead`);
+ }
+ return parsed;
+ }
+
+ async function readSpooled(name: string, absPath: string, declared: number): Promise<Buffer> {
+ const data = await readAbsBytes(name, absPath);
+ if (!data || data.length !== declared) {
+ throw new Error(`agent37 read ${absPath}: truncated (${data?.length ?? 0}/${declared})`);
+ }
+ return Buffer.from(data);
+ }
+
+ async function execRaw(name: string, script: string, timeoutSec: number): Promise<ExecResult> {
+ const uid = randomUUID();
+ const out = `${HOME_DIR}/.qm-exec-${uid}.out`;
+ const err = `${HOME_DIR}/.qm-exec-${uid}.err`;
+ const rcf = `${HOME_DIR}/.qm-exec-${uid}.rc`;
+ const envelope =
+ `__o=$(wc -c < ${out}); __e=$(wc -c < ${err}); printf '%s %s %s\\n' "$__rc" "$__o" "$__e"; ` +
+ `if [ "$__o" -le ${INLINE_LIMIT} ] && [ "$__e" -le ${INLINE_LIMIT} ]; then base64 < ${out}; base64 < ${err}; rm -f ${out} ${err} ${rcf}; fi`;
+ let r: InstanceExecResponse;
+ if (timeoutSec <= EXEC_SYNC_MAX_SEC) {
+ r = await postExec(
+ name,
+ `timeout ${timeoutSec} sh -c ${shq(script)} > ${out} 2> ${err}; __rc=$?; ${envelope}`,
+ timeoutSec,
+ );
+ } else {
+ const body = `timeout ${timeoutSec} sh -c ${shq(script)} > ${out} 2> ${err}; echo $? > ${rcf}`;
+ const start = await postExec(name, `nohup sh -c ${shq(body)} >/dev/null 2>&1 & echo launched`, 30);
+ if (start.exit_code !== 0 || !/launched/.test(start.stdout)) {
+ throw new Error(`agent37 exec ${name}: background launch failed (rc=${start.exit_code})`);
+ }
+ const deadline = Date.now() + timeoutSec * 1000 + EXIT_GRACE_MS;
+ for (;;) {
+ const p = await postExec(name, `[ -f ${rcf} ] && echo settled || echo running`, 30);
+ if (/settled/.test(p.stdout)) break;
+ if (Date.now() > deadline) {
+ throw new Error(`agent37 exec ${name}: no exit after ${timeoutSec}s (+grace); leaving ${rcf}`);
+ }
+ await sleep(EXEC_POLL_MS);
+ }
+ r = await postExec(name, `__rc=$(cat ${rcf}); ${envelope}`, 60);
+ }
+ const text = r.stdout;
+ const nl = text.indexOf("\n");
+ const header = text
+ .slice(0, nl < 0 ? undefined : nl)
+ .trim()
+ .split(/\s+/);
+ if (r.exit_code !== 0 || nl < 0 || header.length !== 3) {
+ throw new Error(`agent37 exec ${name}: bad envelope (rc=${r.exit_code}): ${text.slice(0, 120)}`);
+ }
+ const code = Number.parseInt(header[0]!, 10);
+ const outLen = Number.parseInt(header[1]!, 10);
+ const errLen = Number.parseInt(header[2]!, 10);
+ let outBuf: Buffer;
+ let errBuf: Buffer;
+ if (outLen <= INLINE_LIMIT && errLen <= INLINE_LIMIT) {
+ const b64 = text.slice(nl + 1).replace(/\s+/g, "");
+ const outB64 = Math.ceil(outLen / 3) * 4;
+ outBuf = Buffer.from(b64.slice(0, outB64), "base64");
+ errBuf = Buffer.from(b64.slice(outB64), "base64");
+ if (outBuf.length !== outLen || errBuf.length !== errLen) {
+ throw new Error(
+ `agent37 exec ${name}: truncated stream (${outBuf.length}/${outLen} out, ${errBuf.length}/${errLen} err)`,
+ );
+ }
+ } else {
+ outBuf = await readSpooled(name, out, outLen);
+ errBuf = await readSpooled(name, err, errLen);
+ await postExec(name, `rm -f ${shq(out)} ${shq(err)} ${shq(rcf)}`, 60).catch(
+ swallowAs("agent37-sandbox: spool cleanup", undefined),
+ );
+ }
+ return { stdout: outBuf.toString("utf8"), stderr: errBuf.toString("utf8"), code, timedOut: code === 124 };
+ }
+
+ async function writeAbsBytes(name: string, absPath: string, data: Uint8Array): Promise<void> {
+ const part = `${absPath}.${randomUUID().slice(0, 8)}.part`;
+ const b64 = Buffer.from(data).toString("base64");
+ const mk = await postExec(name, `mkdir -p "$(dirname ${shq(absPath)})" && : > ${shq(part)}`, 60);
+ if (mk.exit_code !== 0) throw new Error(`agent37 write ${absPath}: mkdir failed (${mk.exit_code})`);
+ try {
+ for (let i = 0; i < b64.length; i += WRITE_CHUNK_B64) {
+ const chunk = b64.slice(i, i + WRITE_CHUNK_B64);
+ const r = await postExec(name, `printf %s ${shq(chunk)} | base64 -d >> ${shq(part)}`, 120);
+ if (r.exit_code !== 0) {
+ throw new Error(`agent37 write ${absPath}: chunk ${i / WRITE_CHUNK_B64} failed (${r.exit_code})`);
+ }
+ }
+ const fin = await postExec(
+ name,
+ `sz=$(wc -c < ${shq(part)}) && mv -f ${shq(part)} ${shq(absPath)} && printf %s "$sz"`,
+ 60,
+ );
+ const written = Number.parseInt(fin.stdout.trim(), 10);
+ if (fin.exit_code !== 0 || written !== data.length) {
+ throw new Error(`agent37 write ${absPath} failed (rc=${fin.exit_code}, ${written}/${data.length} bytes)`);
+ }
+ } catch (e) {
+ await postExec(name, `rm -f ${shq(part)}`, 60).catch(swallowAs("agent37-sandbox: write part cleanup", undefined));
+ throw e;
+ }
+ }
+
+ async function readAbsBytes(name: string, absPath: string): Promise<Uint8Array | null> {
+ const script =
+ `[ -e ${shq(absPath)} ] || exit ${MISSING_RC}; s=$(wc -c < ${shq(absPath)}); echo "$s"; ` +
+ `if [ "$s" -le ${READ_CHUNK} ]; then base64 < ${shq(absPath)}; fi`;
+ const r = await postExec(name, script, 120);
+ if (r.exit_code === MISSING_RC) return null;
+ if (r.exit_code !== 0) {
+ throw new Error(`agent37 read ${absPath} failed (${r.exit_code}): ${r.stderr.slice(0, 200)}`);
+ }
+ const nl = r.stdout.indexOf("\n");
+ const declared = Number.parseInt(r.stdout.slice(0, nl < 0 ? undefined : nl).trim(), 10);
+ if (!Number.isFinite(declared)) throw new Error(`agent37 read ${absPath}: bad size (${r.stdout.slice(0, 40)})`);
+ const parts: Buffer[] = [];
+ if (declared <= READ_CHUNK) {
+ parts.push(Buffer.from(r.stdout.slice(nl + 1).replace(/\s+/g, ""), "base64"));
+ } else {
+ for (let i = 0; i < Math.ceil(declared / READ_CHUNK); i++) {
+ const c = await postExec(
+ name,
+ `dd if=${shq(absPath)} bs=${READ_CHUNK} skip=${i} count=1 2>/dev/null | base64`,
+ 120,
+ );
+ if (c.exit_code !== 0) throw new Error(`agent37 read ${absPath} chunk ${i} failed (${c.exit_code})`);
+ parts.push(Buffer.from(c.stdout.replace(/\s+/g, ""), "base64"));
+ }
+ }
+ const out = Buffer.concat(parts);
+ if (out.length !== declared) throw new Error(`agent37 read ${absPath}: truncated (${out.length}/${declared})`);
+ return out;
+ }
+
+ async function ensureInstance(
+ key: string,
+ name: string,
+ onStatus?: (text: string) => void,
+ ): Promise<{ coldStart: boolean }> {
+ return provisionQueue(key, async () => {
+ if (idByName.has(name)) return { coldStart: false };
+ const existing = await findInstance(name);
+ if (existing) {
+ idByName.set(name, existing.id);
+ if (existing.status !== "running") await ensureRunning(existing.id);
+ return { coldStart: false };
+ }
+ try {
+ onStatus?.("Creating the sandbox…");
+ } catch (error) {
+ void error;
+ }
+ const info = await createInstance(name);
+ idByName.set(name, info.id);
+ return { coldStart: true };
+ });
+ }
+
+ async function ensureScratch(key: string): Promise<{ name: string; coldStart: boolean }> {
+ const name = spriteScopeName(`${prefix}-scratch`, key);
+ return provisionQueue(`scratch:${key}`, async () => {
+ scratchKeyByName.set(name, key);
+ const active = activeScratch.get(name) ?? 0;
+ if (active === 0 && !idByName.has(name)) {
+ await deleteInstance(name).catch(swallowAs("agent37-sandbox: stale scratch delete", undefined));
+ const info = await createInstance(name);
+ idByName.set(name, info.id);
+ }
+ activeScratch.set(name, active + 1);
+ return { name, coldStart: active === 0 };
+ });
+ }
+
+ const profile: AgentComputerProfile = {
+ backend: "agent37",
+ writablePersistence: "resident_disk",
+ processSessions: true,
+ egressEnforcement: "none",
+ spec: {
+ os: "Debian 12, Agent37 sandbox (sleeps when idle; the whole disk persists)",
+ runtimes: ["Node 24", "Python 3"],
+ get tools() {
+ return visibleTools(["git", "curl", "jq", "tar", "python3", ...(opts.extraTools ?? [])]);
+ },
+ get notInstalled() {
+ return visibleNotInstalled(["gh", "aws", "gcloud", "kubectl", "flyctl", "glab"], opts.extraTools ?? []);
+ },
+ cpus: resources.cpu,
+ memoryMb: resources.memory * 1024,
+ diskGb: resources.disk,
+ homeDir: HOME_DIR,
+ workdir: workspaceDir,
+ },
+ };
+
+ const procIo: ExecProcessIo = {
+ async run(handle, command, execOpts): Promise<ExecResult> {
+ const timeoutSec = execOpts?.timeoutMs ? Math.ceil(execOpts.timeoutMs / 1000) : defaultTimeoutSec;
+ return execRaw(handle.id, command, timeoutSec);
+ },
+ };
+ const procSessions = createExecProcessSessions(procIo);
+
+ const execFileOps = createExecFileOps({
+ label: "agent37",
+ exec: (id, script, t) => execRaw(id, script, t),
+ writeInline: (id, abs, data) => writeAbsBytes(id, abs, data),
+ });
+
+ const blobSigningSecret = opts.capabilitySecret ?? opts.signingSecret;
+ const blobStaging =
+ opts.blobTransfer && blobSigningSecret && opts.apiBaseUrl
+ ? createExecBlobStaging({
+ label: "agent37",
+ exec: (id, script, t) => execRaw(id, script, t),
+ proxyPrefix: proxyExportPrefix,
+ apiBaseUrl: opts.apiBaseUrl,
+ capabilityHeader: CAPABILITY_HEADER,
+ mintToken: (grant) =>
+ mintCapabilityToken(
+ {
+ actorId: "agent37-sandbox",
+ aud: BLOB_TRANSFER_AUD,
+ scopeId: "personal:agent37-sandbox",
+ blob: grant,
+ exp: Date.now() + BLOB_TRANSFER_TTL_MS,
+ },
+ blobSigningSecret,
+ ),
+ })
+ : null;
+
+ const execBackup = createExecBackup({
+ label: "agent37",
+ exec: (id, script, t) => execRaw(id, script, t),
+ readAbsBytes,
+ defaultHomeDir: HOME_DIR,
+ ephemeralCredentialPrefixes: ephemeralCredLinkPaths(opts.credentialPaths ?? []).map(({ rel }) => rel),
+ });
+
+ const sandbox: Sandbox = {
+ profile,
+ startProcess: procSessions.startProcess,
+ readProcess: procSessions.readProcess,
+ writeStdin: procSessions.writeStdin,
+ signalProcess: procSessions.signalProcess,
+ listProcesses: procSessions.listProcesses,
+ ...execFileOps,
+ ...(blobStaging
+ ? {
+ async stageIn(handle: SandboxHandle, destRelPath: string, blobId: string): Promise<void> {
+ await blobStaging.stageInAbs(handle, posixJoin(handle.rootDir, destRelPath), blobId);
+ },
+ async stageOut(handle: SandboxHandle, srcRelPath: string): Promise<string> {
+ return blobStaging.stageOutAbs(handle, posixJoin(handle.rootDir, srcRelPath));
+ },
+ }
+ : {}),
+
+ async provision(layers: WorkspaceLayer[], provOpts?: ProvisionOptions): Promise<SandboxHandle> {
+ const scratch = provOpts?.scratch;
+ const writable = layers.find((l) => l.mode === "rw") ?? layers[0];
+ const scope = writable?.scopeId ?? "default";
+ let name: string;
+ let coldStart: boolean;
+ if (scratch) {
+ ({ name, coldStart } = await ensureScratch(scratch.key));
+ } else {
+ name = spriteScopeName(prefix, scope);
+ scopeByName.set(name, scope);
+ ({ coldStart } = await ensureInstance(scope, name, provOpts?.onStatus));
+ }
+
+ const forceEgress = !!opts.egressProxyUrl && !!provOpts?.egressToken;
+ const turnEnv = Object.fromEntries(
+ Object.entries(provOpts?.env ?? {}).filter(([k]) => !DROPPED_PROXY_ENV.has(k)),
+ );
+ const env = {
+ ...turnEnv,
+ ...(forceEgress ? forceThroughProxyEnv(opts.egressProxyUrl!, provOpts!.egressToken!) : {}),
+ };
+ const handle: SandboxHandle = {
+ id: name,
+ rootDir: workspaceDir,
+ homeDir: HOME_DIR,
+ coldStart,
+ ...(scratch ? { scratch: true } : {}),
+ ...(Object.keys(env).length ? { env } : {}),
+ };
+
+ try {
+ const credLinks = scratch ? "" : ` && ${ephemeralCredLinkScript(HOME_DIR, opts.credentialPaths ?? [])}`;
+ const prep = await execRaw(name, `mkdir -p ${shq(workspaceDir)}${credLinks}`, 60);
+ if (prep.code !== 0)
+ throw new Error(`agent37 provision prep failed: ${(prep.stderr || prep.stdout).slice(0, 200)}`);
+
+ await materializeRoLayers(
+ workspace,
+ layers,
+ handle,
+ {
+ readFile: (h, rel) => sandbox.readFile(h, rel),
+ writeFileBytes: (h, rel, data) => sandbox.writeFileBytes(h, rel, data),
+ exec: (script, t) => execRaw(name, script, t),
+ },
+ { manifest: RO_LAYERS_MANIFEST, tar: RO_LAYERS_TAR, label: "agent37" },
+ );
+
+ return handle;
+ } catch (err) {
+ await sandbox.teardown(handle).catch(swallowAs("agent37-sandbox: teardown after failed provision", undefined));
+ throw err;
+ }
+ },
+
+ async run(handle, command, execOpts?: ExecOptions): Promise<ExecResult> {
+ const timeoutSec = execOpts?.timeoutMs ? Math.ceil(execOpts.timeoutMs / 1000) : defaultTimeoutSec;
+ const exports = Object.entries(handle.env ?? {})
+ .map(([k, v]) => `export ${k}=${shq(v)}`)
+ .join("; ");
+ const script = `${nonInteractiveShellPrefix()}${exports ? exports + "; " : ""}cd ${handle.rootDir} 2>/dev/null; ${command}`;
+ const signal = execOpts?.signal;
+ if (!signal) return execRaw(handle.id, script, timeoutSec);
+ const killUid = randomUUID();
+ const fireKill = () => {
+ execRaw(handle.id, killScript(killUid), 15).catch(swallowAs("agent37-sandbox: kill in-flight exec", undefined));
+ };
+ if (signal.aborted) fireKill();
+ const onAbort = () => fireKill();
+ signal.addEventListener("abort", onAbort, { once: true });
+ try {
+ return await execRaw(handle.id, killableScript(script, killUid), timeoutSec);
+ } finally {
+ signal.removeEventListener("abort", onAbort);
+ }
+ },
+
+ async writeFileBytes(handle, relPath, data): Promise<void> {
+ await writeAbsBytes(handle.id, posixJoin(handle.rootDir, relPath), data);
+ },
+ async writeFile(handle, relPath, data): Promise<void> {
+ await sandbox.writeFileBytes(handle, relPath, Buffer.from(data, "utf8"));
+ },
+ async readFileBytes(handle, relPath): Promise<Uint8Array | null> {
+ return readAbsBytes(handle.id, posixJoin(handle.rootDir, relPath));
+ },
+ async readFile(handle, relPath): Promise<string | null> {
+ const bytes = await sandbox.readFileBytes(handle, relPath);
+ return bytes === null ? null : Buffer.from(bytes).toString("utf8");
+ },
+
+ backupComputer: execBackup.backupComputer,
+
+ async teardown(handle, tdOpts?: TeardownOptions): Promise<void> {
+ if (handle.scratch) {
+ const key = scratchKeyByName.get(handle.id);
+ return provisionQueue(key ? `scratch:${key}` : handle.id, async () => {
+ const remaining = (activeScratch.get(handle.id) ?? 1) - 1;
+ if (remaining > 0) {
+ activeScratch.set(handle.id, remaining);
+ return;
+ }
+ activeScratch.delete(handle.id);
+ if (tdOpts?.destroy) await deleteInstance(handle.id);
+ else await deleteInstance(handle.id).catch(swallowAs("agent37-sandbox: scratch delete", undefined));
+ });
+ }
+ if (!tdOpts?.destroy) return;
+ await deleteInstance(handle.id).catch((e) => {
+ const scope = scopeByName.get(handle.id);
+ opts.onError?.({
+ category: "sandbox_teardown",
+ code: "instance_delete_failed",
+ message: errMessage(e),
+ ...(scope ? { scopeLabel: scope } : {}),
+ });
+ });
+ },
+ };
+
+ return sandbox;
+}
diff --git a/src/sandbox/sandbox-routing.ts b/src/sandbox/sandbox-routing.ts
index 5a31757e5..374fd5e81 100644
--- a/src/sandbox/sandbox-routing.ts
+++ b/src/sandbox/sandbox-routing.ts
@@ -14,7 +14,7 @@ import {
type TeardownOptions,
} from "./sandbox.ts";
-export type SandboxBackendName = "sprites" | "aws" | "local" | "smolmachines" | "porter";
+export type SandboxBackendName = "sprites" | "aws" | "local" | "smolmachines" | "porter" | "agent37";
export interface SandboxRoute {
backend: SandboxBackendName;
diff --git a/src/wiring.ts b/src/wiring.ts
index f955751bc..06d25343d 100644
--- a/src/wiring.ts
+++ b/src/wiring.ts
@@ -125,6 +125,7 @@ import { createAwsSandbox, type StoredMicrovm } from "./sandbox/aws-sandbox.ts";
import { createLocalSandbox } from "./sandbox/local-sandbox.ts";
import { createSpritesSandbox } from "./sandbox/sprites-sandbox.ts";
import { createSmolmachinesSandbox } from "./sandbox/smolmachines-sandbox.ts";
+import { createAgent37Sandbox } from "./sandbox/agent37-sandbox.ts";
import { createPorterSandbox } from "./sandbox/porter-sandbox.ts";
import {
createSandboxRouter,
@@ -658,6 +659,17 @@ export function buildApp(
...(config.apiBaseUrl ? { apiBaseUrl: config.apiBaseUrl } : {}),
onError: sandboxOnError,
});
+ const buildAgent37 = (): Sandbox =>
+ createAgent37Sandbox(workspace, {
+ ...config.agent37Sandbox,
+ blobTransfer,
+ extraTools: deploymentLayer.advertisedTools,
+ credentialPaths: deploymentLayer.credentialPaths,
+ ...(config.signingSecret ? { signingSecret: config.signingSecret } : {}),
+ ...(config.capabilitySecret ? { capabilitySecret: config.capabilitySecret } : {}),
+ ...(config.apiBaseUrl ? { apiBaseUrl: config.apiBaseUrl } : {}),
+ onError: sandboxOnError,
+ });
const buildAws = (): Sandbox => {
if (!config.awsSandbox.s3Bucket) throw new Error("SANDBOX_BACKEND=aws requires AWS_SANDBOX_S3_BUCKET");
return createAwsSandbox(workspace, {
@@ -688,6 +700,7 @@ export function buildApp(
smolmachines: buildSmolmachines,
aws: buildAws,
porter: buildPorter,
+ agent37: buildAgent37,
};
const sandboxBackends: Partial<Record<SandboxBackendName, Sandbox>> = {
[config.sandboxBackend]: buildBackend[config.sandboxBackend](),
diff --git a/test/agent37-sandbox.test.ts b/test/agent37-sandbox.test.ts
new file mode 100644
index 000000000..549901ee9
--- /dev/null
+++ b/test/agent37-sandbox.test.ts
@@ -0,0 +1,206 @@
+import { test, after, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createAgent37Sandbox } from "../src/sandbox/agent37-sandbox.ts";
+import { spriteScopeName } from "../src/sandbox/sprites-sandbox.ts";
+import { createLocalWorkspaceStore } from "../src/workspace/workspace-store.ts";
+import { supportsProcessSessions } from "../src/sandbox/sandbox.ts";
+import { scopeId } from "../src/types.ts";
+import { mintCapabilityToken, EGRESS_PROXY_AUD } from "../src/auth/capability-token.ts";
+import { installFakeAgent37, FAKE_AGENT37_API_KEY, type FakeAgent37 } from "./support/fake-agent37.ts";
+import type { Sandbox } from "../src/sandbox/sandbox.ts";
+
+let fake: FakeAgent37;
+let sandbox: Sandbox;
+const scope = scopeId("personal", "tester");
+const layers = [{ scopeId: scope, mountPath: "/", mode: "rw" as const }];
+
+function make(extra: Record<string, unknown> = {}): Sandbox {
+ return createAgent37Sandbox(createLocalWorkspaceStore(mkdtempSync(join(tmpdir(), "a37-ws-"))), {
+ apiKey: FAKE_AGENT37_API_KEY,
+ namePrefix: "qmt",
+ fetchImpl: fake.fetchImpl,
+ ...extra,
+ });
+}
+
+beforeEach(() => {
+ fake = installFakeAgent37();
+ sandbox = make();
+});
+after(() => fake?.cleanup());
+
+test("provision runs commands with env and cwd", async () => {
+ const h = await sandbox.provision(layers, { env: { MY_VAR: "v1" } });
+ assert.equal(h.coldStart, true);
+ const r = await sandbox.run(h, "pwd; echo VAR=$MY_VAR");
+ assert.equal(r.code, 0);
+ assert.match(r.stdout, /workspace/);
+ assert.match(r.stdout, /VAR=v1/);
+});
+
+test("streams and exit codes are exact", async () => {
+ const h = await sandbox.provision(layers);
+ const r = await sandbox.run(h, "echo out; echo err >&2; exit 3");
+ assert.equal(r.code, 3);
+ assert.equal(r.stdout.trim(), "out");
+ assert.equal(r.stderr.trim(), "err");
+});
+
+test("file roundtrip incl. large binary and missing file", async () => {
+ const h = await sandbox.provision(layers);
+ await sandbox.writeFile(h, "a/b.txt", "hello\n");
+ assert.equal(await sandbox.readFile(h, "a/b.txt"), "hello\n");
+ assert.equal(await sandbox.readFile(h, "nope.txt"), null);
+ const big = Buffer.alloc(200 * 1024);
+ for (let i = 0; i < big.length; i++) big[i] = (i * 7) % 256;
+ await sandbox.writeFileBytes(h, "big.bin", big);
+ const back = await sandbox.readFileBytes(h, "big.bin");
+ assert.ok(back && Buffer.from(back).equals(big));
+ const huge = Buffer.alloc(1300 * 1024);
+ for (let i = 0; i < huge.length; i++) huge[i] = (i * 13) % 256;
+ await sandbox.writeFileBytes(h, "huge.bin", huge);
+ const hugeBack = await sandbox.readFileBytes(h, "huge.bin");
+ assert.ok(hugeBack && Buffer.from(hugeBack).equals(huge));
+});
+
+test("every exec request stays under the single-argument limit of the host", async () => {
+ const h = await sandbox.provision(layers);
+ await sandbox.writeFileBytes(h, "wide.bin", Buffer.alloc(600 * 1024, 7));
+ const longest = Math.max(...fake.execScripts().map((s) => Buffer.byteLength(s)));
+ assert.ok(longest < 100 * 1024, `longest exec command was ${longest} bytes`);
+});
+
+test("empty file roundtrip", async () => {
+ const h = await sandbox.provision(layers);
+ await sandbox.writeFileBytes(h, "empty.bin", Buffer.alloc(0));
+ const back = await sandbox.readFileBytes(h, "empty.bin");
+ assert.ok(back);
+ assert.equal(back.length, 0);
+});
+
+test("process sessions capability works end to end", async () => {
+ assert.ok(supportsProcessSessions(sandbox));
+ if (!supportsProcessSessions(sandbox)) return;
+ const h = await sandbox.provision(layers);
+ const { processId } = await sandbox.startProcess(h, "echo one; echo two");
+ let cursor = 0,
+ chunks = "",
+ state = "running";
+ for (let i = 0; i < 10 && state === "running"; i++) {
+ const r = await sandbox.readProcess(h, processId, { sinceCursor: cursor });
+ chunks += r.chunks;
+ cursor = r.cursor;
+ state = r.status.state;
+ }
+ assert.match(chunks, /one/);
+ assert.match(chunks, /two/);
+});
+
+test("force-through proxy env is set when a proxy url and token are present", async () => {
+ const s = make({ egressProxyUrl: "https://proxy.example.com" });
+ const token = await mintCapabilityToken(
+ { actorId: "tester", scopeId: scope, aud: EGRESS_PROXY_AUD, exp: Date.now() + 600_000 },
+ "secret",
+ );
+ const h = await s.provision(layers, { egressToken: token });
+ const r = await s.run(h, "echo PROXY=$HTTPS_PROXY");
+ assert.match(r.stdout, /PROXY=https?:\/\/[^ ]*proxy\.example\.com/);
+});
+
+test("no proxy env without a proxy url", async () => {
+ const h = await sandbox.provision(layers, { egressToken: "ignored" });
+ assert.equal(h.env?.HTTPS_PROXY, undefined);
+});
+
+test("instance is reused across provisions and warm start is reported", async () => {
+ const a = await sandbox.provision(layers);
+ const b = await sandbox.provision(layers);
+ assert.equal(a.id, b.id);
+ assert.equal(b.coldStart, false);
+ assert.equal(fake.names().filter((n) => n === a.id).length, 1);
+});
+
+test("exec on a sleeping instance wakes it and retries", async () => {
+ const h = await sandbox.provision(layers);
+ await sandbox.writeFile(h, "keep.txt", "still here\n");
+ fake.sleep(h.id);
+ const r = await sandbox.run(h, "cat keep.txt");
+ assert.equal(r.code, 0);
+ assert.equal(r.stdout, "still here\n");
+ assert.equal(fake.instance(h.id)?.status, "running");
+ assert.ok(fake.calls.some((c) => c.method === "POST" && /\/start$/.test(c.path)));
+});
+
+test("scratch instances are created on demand and deleted at release", async () => {
+ const h = await sandbox.provision(layers, { scratch: { key: "job-1" } });
+ assert.equal(h.scratch, true);
+ assert.ok(fake.instance(h.id));
+ await sandbox.teardown(h);
+ assert.equal(fake.instance(h.id), null);
+});
+
+test("teardown without destroy keeps the instance; destroy deletes it", async () => {
+ const h = await sandbox.provision(layers);
+ await sandbox.teardown(h);
+ assert.ok(fake.instance(h.id));
+ await sandbox.teardown(h, { destroy: true });
+ assert.equal(fake.instance(h.id), null);
+});
+
+test("large command output survives the API's output cap exactly", async () => {
+ const h = await sandbox.provision(layers);
+ const r = await sandbox.run(h, "python3 -c \"print('x' * (900 * 1024), end='')\"");
+ assert.equal(r.code, 0);
+ assert.equal(r.stdout.length, 900 * 1024);
+ assert.equal(r.stdout, "x".repeat(900 * 1024));
+});
+
+test("an instance already named after the scope is adopted instead of duplicated", async () => {
+ await fake.fetchImpl("https://api.agent37.com/v1/instances", {
+ method: "POST",
+ body: JSON.stringify({ name: spriteScopeName("qmt", scope) }),
+ });
+ const h = await sandbox.provision(layers);
+ assert.equal(h.coldStart, false);
+ const r = await sandbox.run(h, "echo alive");
+ assert.equal(r.stdout.trim(), "alive");
+ assert.equal(fake.names().filter((n) => n === h.id).length, 1);
+});
+
+test("timeouts beyond the API's sync exec ceiling run detached and poll to completion", async () => {
+ const h = await sandbox.provision(layers);
+ const r = await sandbox.run(h, "echo long-path-ok; echo warn >&2; exit 9", { timeoutMs: 400_000 });
+ assert.equal(r.code, 9);
+ assert.equal(r.stdout.trim(), "long-path-ok");
+ assert.equal(r.stderr.trim(), "warn");
+ const leftovers = await sandbox.run(h, "ls /home/node/.qm-exec-*.rc 2>/dev/null | wc -l");
+ assert.equal(leftovers.stdout.trim(), "0");
+});
+
+test("create requests the template, the default shape and auto sleep", async () => {
+ const h = await sandbox.provision(layers);
+ const created = fake.instance(h.id);
+ assert.equal(created?.template, "agent37-qm-computer");
+ assert.equal(created?.autoSleep, true);
+ assert.deepEqual(created?.resources, { cpu: 2, memory: 4, disk: 8 });
+});
+
+test("configured resources are requested at create and advertised in the profile", async () => {
+ const s = make({ template: "my-computer", cpus: 4, memoryGb: 8, diskGb: 20 });
+ const h = await s.provision(layers);
+ assert.equal(fake.instance(h.id)?.template, "my-computer");
+ assert.deepEqual(fake.instance(h.id)?.resources, { cpu: 4, memory: 8, disk: 20 });
+ assert.equal(s.profile.spec?.cpus, 4);
+ assert.equal(s.profile.spec?.memoryMb, 8192);
+ assert.equal(s.profile.spec?.diskGb, 20);
+});
+
+test("profile advertises resident disk and process sessions", () => {
+ assert.equal(sandbox.profile.backend, "agent37");
+ assert.equal(sandbox.profile.writablePersistence, "resident_disk");
+ assert.equal(sandbox.profile.processSessions, true);
+ assert.equal(sandbox.profile.egressEnforcement, "none");
+});
diff --git a/test/config.test.ts b/test/config.test.ts
index 7445cca35..fb50cb88a 100644
--- a/test/config.test.ts
+++ b/test/config.test.ts
@@ -356,6 +356,8 @@ test("SANDBOX_BACKEND: unset defaults to local (dev only); the secondary must be
"sprites",
);
assert.throws(() => loadConfig({ SANDBOX_BACKEND: "sprites" }), /SPRITES_TOKEN/);
+ assert.throws(() => loadConfig({ SANDBOX_BACKEND: "agent37" }), /AGENT37_API_KEY/);
+ assert.equal(loadConfig({ SANDBOX_BACKEND: "agent37", AGENT37_API_KEY: "sk_live_k" }).sandboxBackend, "agent37");
assert.throws(
() => loadConfig({ SANDBOX_SECONDARY_BACKEND: "fly" }),
/SANDBOX_SECONDARY_BACKEND="fly" is not recognized/,
diff --git a/test/support/fake-agent37.ts b/test/support/fake-agent37.ts
new file mode 100644
index 000000000..5f977598e
--- /dev/null
+++ b/test/support/fake-agent37.ts
@@ -0,0 +1,195 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface Agent37Call {
+ method: string;
+ path: string;
+ script?: string;
+}
+
+interface FakeInstance {
+ id: string;
+ name: string | null;
+ status: string;
+ template?: string;
+ autoSleep?: boolean;
+ resources?: Record<string, number>;
+ home: string;
+}
+
+export interface FakeInstanceView {
+ status: string;
+ template?: string;
+ autoSleep?: boolean;
+ resources?: Record<string, number>;
+}
+
+export interface FakeAgent37 {
+ fetchImpl: typeof fetch;
+ calls: Agent37Call[];
+ names(): string[];
+ instance(name: string): FakeInstanceView | null;
+ sleep(name: string): void;
+ execScripts(): string[];
+ cleanup(): void;
+}
+
+export const FAKE_AGENT37_API_KEY = "sk_live_test_key";
+const OUTPUT_CAP = 512 * 1024;
+
+export function installFakeAgent37(): FakeAgent37 {
+ const root = mkdtempSync(join(tmpdir(), "fake-a37-"));
+ const instances = new Map<string, FakeInstance>();
+ const execScripts: string[] = [];
+ const calls: Agent37Call[] = [];
+ let nextId = 1;
+
+ const live = (): FakeInstance[] => [...instances.values()].filter((i) => i.status !== "deleted").reverse();
+ const byName = (name: string): FakeInstance | undefined => live().find((i) => i.name === name);
+
+ const create = (body: {
+ name?: string | null;
+ template?: string;
+ auto_sleep?: boolean;
+ resources?: Record<string, number>;
+ }): FakeInstance => {
+ const id = `inst${nextId++}`;
+ const m: FakeInstance = {
+ id,
+ name: body.name ?? null,
+ status: "provisioning",
+ ...(body.template ? { template: body.template } : {}),
+ ...(body.auto_sleep !== undefined ? { autoSleep: body.auto_sleep } : {}),
+ ...(body.resources ? { resources: body.resources } : {}),
+ home: join(root, id),
+ };
+ mkdirSync(m.home, { recursive: true });
+ instances.set(id, m);
+ return m;
+ };
+
+ const settle = (m: FakeInstance): FakeInstance => {
+ if (m.status === "provisioning" || m.status === "waking" || m.status === "starting") m.status = "running";
+ return m;
+ };
+
+ const remap = (m: FakeInstance, script: string): string => {
+ const homeRe = m.home.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+ const remapPath = new RegExp(`${homeRe}/tmp/|${homeRe}(?![A-Za-z0-9._-])|/tmp/`, "g");
+ return (
+ `export HOME=${JSON.stringify(m.home)}; ` +
+ script
+ .replace(/\btimeout \d+ /g, "")
+ .replace(/\/home\/node/g, m.home)
+ .replace(remapPath, (mm) => (mm.startsWith(m.home) ? mm : `${m.home}/tmp/`))
+ );
+ };
+
+ const runExec = (m: FakeInstance, script: string): Response => {
+ execScripts.push(script);
+ mkdirSync(join(m.home, "tmp"), { recursive: true });
+ const r = spawnSync("sh", ["-c", remap(m, script)], {
+ encoding: "buffer",
+ maxBuffer: 128 * 1024 * 1024,
+ env: { ...process.env, COPYFILE_DISABLE: "1" },
+ });
+ const code = r.status ?? (r.signal ? 137 : -1);
+ const stdout = (r.stdout ?? Buffer.alloc(0)).toString("utf8");
+ const stderr = (r.stderr ?? Buffer.alloc(0)).toString("utf8");
+ return Response.json({
+ exit_code: code,
+ stdout: stdout.slice(0, OUTPUT_CAP),
+ stderr: stderr.slice(0, OUTPUT_CAP),
+ truncated: stdout.length > OUTPUT_CAP || stderr.length > OUTPUT_CAP,
+ });
+ };
+
+ const info = (m: FakeInstance) => ({
+ id: m.id,
+ status: m.status,
+ template: m.template ?? "agent37-qm-computer",
+ resources: m.resources ?? {},
+ name: m.name,
+ auto_sleep: m.autoSleep === true,
+ });
+
+ const error = (status: number, code: string, message: string): Response =>
+ Response.json({ error: { code, message } }, { status });
+
+ const toBuf = (body: unknown): Buffer => {
+ if (Buffer.isBuffer(body)) return body;
+ if (typeof body === "string") return Buffer.from(body);
+ return Buffer.alloc(0);
+ };
+
+ const fetchImpl: typeof fetch = async (input, init) => {
+ const url = new URL(typeof input === "string" ? input : input.toString());
+ const method = init?.method ?? "GET";
+ calls.push({ method, path: url.pathname });
+ if (url.pathname === "/v1/instances" && method === "GET") {
+ return Response.json({ data: live().map(info) });
+ }
+ if (url.pathname === "/v1/instances" && method === "POST") {
+ const body = JSON.parse(toBuf(init?.body).toString() || "{}");
+ return Response.json(info(create(body)), { status: 201 });
+ }
+ const sub = /^\/v1\/instances\/([^/]+)(?:\/(exec|start|stop))?$/.exec(url.pathname);
+ if (sub) {
+ const m = instances.get(decodeURIComponent(sub[1]!));
+ if (!m || m.status === "deleted") return error(404, "not_found", "Instance not found.");
+ if (sub[2] === "exec") {
+ if (m.status !== "running") {
+ return error(400, "invalid_request", "Only running instances can execute commands.");
+ }
+ const body = JSON.parse(toBuf(init?.body).toString() || "{}") as { command?: string };
+ const script = body.command ?? "";
+ calls[calls.length - 1]!.script = script;
+ return runExec(m, script);
+ }
+ if (sub[2] === "start") {
+ if (m.status === "running") return Response.json({ id: m.id, status: "running" });
+ if (m.status !== "stopped" && m.status !== "sleeping") {
+ return error(400, "invalid_request", "Only stopped or sleeping instances can be started.");
+ }
+ m.status = m.status === "sleeping" ? "waking" : "starting";
+ return Response.json({ id: m.id, status: m.status });
+ }
+ if (sub[2] === "stop") {
+ m.status = "stopped";
+ return Response.json({ id: m.id, status: "stopped" });
+ }
+ if (method === "GET") return Response.json(info(settle(m)));
+ if (method === "DELETE") {
+ rmSync(m.home, { recursive: true, force: true });
+ m.status = "deleted";
+ return Response.json({ id: m.id, deleted: true });
+ }
+ }
+ return error(404, "not_found", "No such endpoint.");
+ };
+
+ return {
+ fetchImpl,
+ calls,
+ names: () => live().map((m) => m.name ?? m.id),
+ instance: (name) => {
+ const m = byName(name);
+ return m
+ ? {
+ status: m.status,
+ ...(m.template ? { template: m.template } : {}),
+ ...(m.autoSleep !== undefined ? { autoSleep: m.autoSleep } : {}),
+ ...(m.resources ? { resources: m.resources } : {}),
+ }
+ : null;
+ },
+ sleep: (name) => {
+ const m = byName(name);
+ if (m) m.status = "sleeping";
+ },
+ execScripts: () => [...execScripts],
+ cleanup: () => rmSync(root, { recursive: true, force: true }),
+ };
+}