@agentstep/agent-sdk 0.1.0 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "license": "Apache-2.0",
   "name": "@agentstep/agent-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "main": "src/index.ts",

package/src/db/agents.ts

@@ -19,7 +19,7 @@ function hydrate(row: AgentRow, ver: AgentVersionRow): Agent {
     system: ver.system,
     tools: JSON.parse(ver.tools_json) as ToolConfig[],
     mcp_servers: JSON.parse(ver.mcp_servers_json) as Record<string, McpServerConfig>,
-    backend: (ver.backend ?? "claude") as BackendName,
+    engine: (ver.backend ?? "claude") as BackendName,
     webhook_url: ver.webhook_url ?? null,
     webhook_events: ver.webhook_events_json ? (JSON.parse(ver.webhook_events_json) as string[]) : ["session.status_idle", "session.status_running", "session.error"],
     threads_enabled: Boolean(ver.threads_enabled),
@@ -129,7 +129,7 @@ export function updateAgent(
       input.system ?? existing.system,
       JSON.stringify(input.tools ?? existing.tools),
       JSON.stringify(input.mcp_servers ?? existing.mcp_servers),
-      existing.backend,
+      existing.engine,
       input.webhook_url !== undefined ? input.webhook_url : existing.webhook_url,
       JSON.stringify(input.webhook_events ?? existing.webhook_events),
       input.threads_enabled !== undefined ? (input.threads_enabled ? 1 : 0) : (existing.threads_enabled ? 1 : 0),

package/src/handlers/agents.ts

@@ -4,7 +4,7 @@ import { createAgent, getAgent, updateAgent, archiveAgent, listAgents } from "..
 import { resolveBackend } from "../backends/registry";
 import { isProxied, markProxied, unmarkProxied } from "../db/proxy";
 import { forwardToAnthropic, validateAnthropicProxy } from "../proxy/forward";
-import { badRequest, notFound } from "../errors";
+import { badRequest, notFound, conflict } from "../errors";
 
 const ToolSchema = z.union([
   z.object({
@@ -39,7 +39,7 @@ const CreateSchema = z.object({
   system: z.string().nullish(),
   tools: z.array(ToolSchema).optional(),
   mcp_servers: McpServerSchema.optional(),
-  backend: z.enum(["claude", "opencode", "codex", "anthropic", "gemini", "factory"]).optional(),
+  engine: z.enum(["claude", "opencode", "codex", "anthropic", "gemini", "factory"]).optional(),
   webhook_url: z.string().url().optional(),
   webhook_events: z.array(z.string()).optional(),
   threads_enabled: z.boolean().optional(),
@@ -76,7 +76,13 @@ export function handleCreateAgent(request: Request): Promise<Response> {
       throw badRequest(`invalid body: ${parsed.error.issues.map((i) => i.message).join("; ")}`);
     }
 
-    const backendName = parsed.data.backend ?? "claude";
+    // Check for duplicate name
+    const existing = listAgents({ limit: 1000 });
+    if (existing.some(a => a.name === parsed.data.name)) {
+      throw conflict(`Agent with name "${parsed.data.name}" already exists`);
+    }
+
+    const backendName = parsed.data.engine ?? "claude";
 
     if (backendName === "anthropic") {
       const proxyErr = validateAnthropicProxy();

package/src/handlers/environments.ts

@@ -37,7 +37,7 @@ const NetworkingSchema = z.union([
 
 const ConfigSchema = z.object({
   type: z.literal("cloud"),
-  provider: z.enum(["sprites", "docker", "apple", "podman", "e2b", "vercel", "daytona", "fly", "modal"]).optional(),
+  provider: z.enum(["sprites", "docker", "apple-container", "apple-firecracker", "podman", "e2b", "vercel", "daytona", "fly", "modal"]).optional(),
   packages: PackagesSchema,
   networking: NetworkingSchema.optional(),
 });
@@ -68,6 +68,12 @@ export function handleCreateEnvironment(request: Request): Promise<Response> {
       return proxyRes;
     }
 
+    // Check for duplicate name
+    const existingEnvs = listEnvironments({ limit: 1000 });
+    if (existingEnvs.some(e => e.name === parsed.data.name)) {
+      throw conflict(`Environment with name "${parsed.data.name}" already exists`);
+    }
+
     // Pre-flight: check provider is available before creating the environment
     const providerName = parsed.data.config.provider ?? "sprites";
     const provider = await resolveProvider(providerName);
@@ -128,7 +134,7 @@ export function handleDeleteEnvironment(request: Request, id: string): Promise<R
     const env = getEnvironment(id);
     if (!env) throw notFound(`environment ${id} not found`);
     if (hasSessionsAttached(id)) {
-      throw conflict(`environment ${id} still has active sessions attached`);
+      throw conflict(`Cannot delete: environment has active sessions. Archive or delete sessions first.`);
     }
     deleteEnvironment(id);
     return jsonOk({ id, type: "environment_deleted" });

package/src/handlers/ui/app.js

@@ -32,7 +32,7 @@ let lastAppendedRole = "";
 
 let onboardingStep = 0;
 let onboardVaultId = null;
-let onboardBackend = "claude";
+let onboardEngine = "claude";
 
 // ── Init ──
 document.getElementById("apiKeyInput").value = apiKey;
@@ -115,11 +115,11 @@ function renderOnboarding() {
   if (onboardingStep === 0) {
     content = `
       <h2 style="font-size:18px;font-weight:600;color:var(--heading)">Create your first agent</h2>
-      <p style="font-size:13px;color:var(--muted);margin-top:4px">Pick a backend and model to get started.</p>
+      <p style="font-size:13px;color:var(--muted);margin-top:4px">Pick an engine and model to get started.</p>
       <div style="display:flex;flex-direction:column;gap:12px;margin-top:16px;width:100%">
         <div class="form-group"><label class="form-label">Name</label><input class="form-input" id="obAgentName" value="Coder" style="width:100%" /></div>
-        <div class="form-group"><label class="form-label">Backend</label>
-          <select class="form-select" id="obBackend" onchange="updateObModels()" style="width:100%">
+        <div class="form-group"><label class="form-label">Engine</label>
+          <select class="form-select" id="obEngine" onchange="updateObModels()" style="width:100%">
             <option value="claude">Claude — Max subscription or API key</option>
             <option value="opencode">OpenCode — Multi-provider</option>
             <option value="codex">Codex — GPT-5.4 models</option>
@@ -138,9 +138,20 @@ function renderOnboarding() {
         <div class="form-group"><label class="form-label">Name</label><input class="form-input" id="obEnvName" value="dev" style="width:100%" /></div>
         <div class="form-group"><label class="form-label">Provider</label>
           <select class="form-select" id="obProvider" onchange="onboardProvider=this.value" style="width:100%">
-            <option value="docker">Docker — Local containers (~3s)</option>
-            <option value="sprites">sprites.dev — Cloud containers (~2s)</option>
-            <option value="apple">Apple Containers — macOS 26+ (~1s)</option>
+            <optgroup label="Local">
+              <option value="docker">Docker</option>
+              <option value="apple-container">Apple Container (macOS 26+)</option>
+              <option value="apple-firecracker">AgentStep Firecracker microVM (M3+)</option>
+              <option value="podman">Podman</option>
+            </optgroup>
+            <optgroup label="Cloud">
+              <option value="sprites">sprites.dev</option>
+              <option value="e2b">E2B</option>
+              <option value="fly">Fly.io</option>
+              <option value="vercel">Vercel</option>
+              <option value="daytona">Daytona</option>
+              <option value="modal">Modal</option>
+            </optgroup>
           </select>
         </div>
         <button class="btn btn-primary" onclick="onboardCreateEnv()" style="width:100%">Create Environment</button>
@@ -150,7 +161,7 @@ function renderOnboarding() {
     const fields = [];
     const backendKeys = { claude: [{ key: "ANTHROPIC_API_KEY", label: "Anthropic API Key", placeholder: "sk-ant-...", alt: "or CLAUDE_CODE_OAUTH_TOKEN" }], opencode: [{ key: "OPENAI_API_KEY", label: "OpenAI API Key", placeholder: "sk-..." }], codex: [{ key: "OPENAI_API_KEY", label: "OpenAI API Key", placeholder: "sk-..." }], gemini: [{ key: "GEMINI_API_KEY", label: "Gemini API Key", placeholder: "AIza..." }], factory: [{ key: "FACTORY_API_KEY", label: "Factory API Key", placeholder: "fk-..." }] };
     const providerKeys = { sprites: [{ key: "SPRITE_TOKEN", label: "Sprites.dev Token", placeholder: "user/org/.../token" }] };
-    (backendKeys[onboardBackend] || []).forEach(f => fields.push(f));
+    (backendKeys[onboardEngine] || []).forEach(f => fields.push(f));
     (providerKeys[onboardProvider] || []).forEach(f => fields.push(f));
 
     const fieldHtml = fields.map((f, i) => `
@@ -173,7 +184,7 @@ function renderOnboarding() {
       <p style="font-size:13px;color:var(--muted);margin-top:4px">Your agent and environment are set up.</p>
       <div style="background:var(--surface);border:1px solid var(--border);border-radius:8px;padding:12px;margin-top:16px;width:100%;font-size:13px;display:flex;flex-direction:column;gap:6px">
         <div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Agent</span><span style="color:var(--heading)">${esc(agents[0]?.name || "")}</span></div>
-        <div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Backend</span><span style="font-family:var(--mono);font-size:11px">${agents[0]?.backend || ""}</span></div>
+        <div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Engine</span><span style="font-family:var(--mono);font-size:11px">${agents[0]?.engine || ""}</span></div>
         <div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Model</span><span style="font-family:var(--mono);font-size:11px">${agents[0]?.model || ""}</span></div>
         <div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Environment</span><span style="color:var(--heading)">${esc(environments[0]?.name || "")}</span></div>
         ${onboardVaultId ? '<div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Secrets</span><span style="color:var(--success)">✓ Vault configured</span></div>' : '<div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Secrets</span><span style="color:var(--dim)">Using server .env</span></div>'}
@@ -191,7 +202,7 @@ function renderOnboarding() {
 }
 
 function updateObModels() {
-  const backend = document.getElementById("obBackend")?.value || "claude";
+  const backend = document.getElementById("obEngine")?.value || "claude";
   const models = MODELS[backend] || MODELS.claude;
   const el = document.getElementById("obModel");
   if (el) el.innerHTML = models.map(m => `<option value="${m}">${m}</option>`).join("");
@@ -199,16 +210,16 @@ function updateObModels() {
 
 async function onboardCreateAgent() {
   const name = document.getElementById("obAgentName")?.value?.trim();
-  const backend = document.getElementById("obBackend")?.value;
+  const backend = document.getElementById("obEngine")?.value;
   const model = document.getElementById("obModel")?.value;
   if (!name) return;
   try {
-    const body = { name, model, backend };
+    const body = { name, model, engine: backend };
     if (backend === "claude") body.tools = [{ type: "agent_toolset_20260401" }];
     await api("/v1/agents", { method: "POST", body: JSON.stringify(body) });
     const a = await api("/v1/agents?limit=50");
     agents = a.data || [];
-    onboardBackend = backend;
+    onboardEngine = backend;
     onboardingStep = 1; // → environment step
     renderOnboarding();
     showToast("Agent created");
@@ -538,7 +549,7 @@ function renderAgents() {
   if (!agents.length) { el.innerHTML = '<p style="color:var(--dim);font-size:12px;padding:8px">No agents yet</p>'; return; }
   el.innerHTML = agents.map((a) => `
     <div class="card-item">
-      <div><div class="name">${esc(a.name)}</div><div class="detail">${esc(a.model)} / ${a.backend}</div></div>
+      <div><div class="name">${esc(a.name)}</div><div class="detail">${esc(a.model)} / ${a.engine}</div></div>
       <div style="display:flex;gap:4px">
         <button class="btn btn-sm btn-secondary" onclick="showAgentConfig('${esc(a.id)}')">Config</button>
         <button class="btn btn-sm btn-danger" onclick="deleteAgent('${esc(a.id)}')">Delete</button>
@@ -614,8 +625,8 @@ function showCreateAgentModal() {
     <div class="modal">
       <h2>Create Agent</h2>
       <div class="form-group"><label class="form-label">Name</label><input class="form-input" id="agentName" value="Coder" /></div>
-      <div class="form-group"><label class="form-label">Backend</label>
-        <select class="form-select" id="agentBackend" onchange="updateModelOptions()">
+      <div class="form-group"><label class="form-label">Engine</label>
+        <select class="form-select" id="agentEngine" onchange="updateModelOptions()">
           <option value="claude">Claude</option><option value="opencode">OpenCode</option><option value="codex">Codex</option><option value="gemini">Gemini</option><option value="factory">Factory</option>
         </select>
       </div>
@@ -630,18 +641,18 @@ function showCreateAgentModal() {
 }
 
 function updateModelOptions() {
-  const backend = document.getElementById("agentBackend").value;
+  const backend = document.getElementById("agentEngine").value;
   const models = MODELS[backend] || MODELS.claude;
   document.getElementById("agentModel").innerHTML = models.map((m) => `<option value="${m}">${m}</option>`).join("");
 }
 
 async function createAgent() {
   const name = document.getElementById("agentName").value.trim();
-  const backend = document.getElementById("agentBackend").value;
+  const backend = document.getElementById("agentEngine").value;
   const model = document.getElementById("agentModel").value;
   if (!name) return;
   try {
-    const body = { name, model, backend };
+    const body = { name, model, engine: backend };
     if (backend === "claude") body.tools = [{ type: "agent_toolset_20260401" }];
     await api("/v1/agents", { method: "POST", body: JSON.stringify(body) });
     closeModal(); loadResources(); showToast("Agent created");
@@ -660,14 +671,20 @@ function showCreateEnvModal() {
       <div class="form-group"><label class="form-label">Name</label><input class="form-input" id="envName" value="dev" style="width:100%" /></div>
       <div class="form-group"><label class="form-label">Provider</label>
         <select class="form-select" id="envProvider" onchange="toggleEnvToken()" style="width:100%">
-          <option value="docker">Docker — Local containers</option>
-          <option value="sprites">sprites.dev — Cloud containers</option>
-          <option value="apple">Apple Containers — macOS 26+</option>
-          <option value="e2b">E2B — AI sandboxes</option>
-          <option value="vercel">Vercel Sandbox — Firecracker VMs</option>
-          <option value="daytona">Daytona — Dev environments</option>
-          <option value="fly">Fly.io — Global VMs</option>
-          <option value="modal">Modal — Serverless containers</option>
+          <optgroup label="Local">
+            <option value="docker">Docker</option>
+            <option value="apple-container">Apple Container (macOS 26+)</option>
+            <option value="apple-firecracker">AgentStep Firecracker microVM (M3+)</option>
+            <option value="podman">Podman</option>
+          </optgroup>
+          <optgroup label="Cloud">
+            <option value="sprites">sprites.dev</option>
+            <option value="e2b">E2B</option>
+            <option value="fly">Fly.io</option>
+            <option value="vercel">Vercel</option>
+            <option value="daytona">Daytona</option>
+            <option value="modal">Modal</option>
+          </optgroup>
         </select>
       </div>
       <div class="form-group" id="envTokenGroup" style="display:none">

package/src/handlers/ui.ts

@@ -308,7 +308,7 @@ let lastAppendedRole = "";
 
 let onboardingStep = 0;
 let onboardVaultId = null;
-let onboardBackend = "claude";
+let onboardEngine = "claude";
 
 // ── Init ──
 document.getElementById("apiKeyInput").value = apiKey;
@@ -391,11 +391,11 @@ function renderOnboarding() {
   if (onboardingStep === 0) {
     content = \`
       <h2 style="font-size:18px;font-weight:600;color:var(--heading)">Create your first agent</h2>
-      <p style="font-size:13px;color:var(--muted);margin-top:4px">Pick a backend and model to get started.</p>
+      <p style="font-size:13px;color:var(--muted);margin-top:4px">Pick an engine and model to get started.</p>
       <div style="display:flex;flex-direction:column;gap:12px;margin-top:16px;width:100%">
         <div class="form-group"><label class="form-label">Name</label><input class="form-input" id="obAgentName" value="Coder" style="width:100%" /></div>
-        <div class="form-group"><label class="form-label">Backend</label>
-          <select class="form-select" id="obBackend" onchange="updateObModels()" style="width:100%">
+        <div class="form-group"><label class="form-label">Engine</label>
+          <select class="form-select" id="obEngine" onchange="updateObModels()" style="width:100%">
             <option value="claude">Claude — Max subscription or API key</option>
             <option value="opencode">OpenCode — Multi-provider</option>
             <option value="codex">Codex — GPT-5.4 models</option>
@@ -414,9 +414,20 @@ function renderOnboarding() {
         <div class="form-group"><label class="form-label">Name</label><input class="form-input" id="obEnvName" value="dev" style="width:100%" /></div>
         <div class="form-group"><label class="form-label">Provider</label>
           <select class="form-select" id="obProvider" onchange="onboardProvider=this.value" style="width:100%">
-            <option value="docker">Docker — Local containers (~3s)</option>
-            <option value="sprites">sprites.dev — Cloud containers (~2s)</option>
-            <option value="apple">Apple Containers — macOS 26+ (~1s)</option>
+            <optgroup label="Local">
+              <option value="docker">Docker</option>
+              <option value="apple-container">Apple Container (macOS 26+)</option>
+              <option value="apple-firecracker">AgentStep Firecracker microVM (M3+)</option>
+              <option value="podman">Podman</option>
+            </optgroup>
+            <optgroup label="Cloud">
+              <option value="sprites">sprites.dev</option>
+              <option value="e2b">E2B</option>
+              <option value="fly">Fly.io</option>
+              <option value="vercel">Vercel</option>
+              <option value="daytona">Daytona</option>
+              <option value="modal">Modal</option>
+            </optgroup>
           </select>
         </div>
         <button class="btn btn-primary" onclick="onboardCreateEnv()" style="width:100%">Create Environment</button>
@@ -426,7 +437,7 @@ function renderOnboarding() {
     const fields = [];
     const backendKeys = { claude: [{ key: "ANTHROPIC_API_KEY", label: "Anthropic API Key", placeholder: "sk-ant-...", alt: "or CLAUDE_CODE_OAUTH_TOKEN" }], opencode: [{ key: "OPENAI_API_KEY", label: "OpenAI API Key", placeholder: "sk-..." }], codex: [{ key: "OPENAI_API_KEY", label: "OpenAI API Key", placeholder: "sk-..." }], gemini: [{ key: "GEMINI_API_KEY", label: "Gemini API Key", placeholder: "AIza..." }], factory: [{ key: "FACTORY_API_KEY", label: "Factory API Key", placeholder: "fk-..." }] };
     const providerKeys = { sprites: [{ key: "SPRITE_TOKEN", label: "Sprites.dev Token", placeholder: "user/org/.../token" }] };
-    (backendKeys[onboardBackend] || []).forEach(f => fields.push(f));
+    (backendKeys[onboardEngine] || []).forEach(f => fields.push(f));
     (providerKeys[onboardProvider] || []).forEach(f => fields.push(f));
 
     const fieldHtml = fields.map((f, i) => \`
@@ -449,7 +460,7 @@ function renderOnboarding() {
       <p style="font-size:13px;color:var(--muted);margin-top:4px">Your agent and environment are set up.</p>
       <div style="background:var(--surface);border:1px solid var(--border);border-radius:8px;padding:12px;margin-top:16px;width:100%;font-size:13px;display:flex;flex-direction:column;gap:6px">
         <div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Agent</span><span style="color:var(--heading)">\${esc(agents[0]?.name || "")}</span></div>
-        <div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Backend</span><span style="font-family:var(--mono);font-size:11px">\${agents[0]?.backend || ""}</span></div>
+        <div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Engine</span><span style="font-family:var(--mono);font-size:11px">\${agents[0]?.engine || ""}</span></div>
         <div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Model</span><span style="font-family:var(--mono);font-size:11px">\${agents[0]?.model || ""}</span></div>
         <div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Environment</span><span style="color:var(--heading)">\${esc(environments[0]?.name || "")}</span></div>
         \${onboardVaultId ? '<div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Secrets</span><span style="color:var(--success)">✓ Vault configured</span></div>' : '<div style="display:flex;justify-content:space-between"><span style="color:var(--muted)">Secrets</span><span style="color:var(--dim)">Using server .env</span></div>'}
@@ -467,7 +478,7 @@ function renderOnboarding() {
 }
 
 function updateObModels() {
-  const backend = document.getElementById("obBackend")?.value || "claude";
+  const backend = document.getElementById("obEngine")?.value || "claude";
   const models = MODELS[backend] || MODELS.claude;
   const el = document.getElementById("obModel");
   if (el) el.innerHTML = models.map(m => \`<option value="\${m}">\${m}</option>\`).join("");
@@ -475,16 +486,16 @@ function updateObModels() {
 
 async function onboardCreateAgent() {
   const name = document.getElementById("obAgentName")?.value?.trim();
-  const backend = document.getElementById("obBackend")?.value;
+  const backend = document.getElementById("obEngine")?.value;
   const model = document.getElementById("obModel")?.value;
   if (!name) return;
   try {
-    const body = { name, model, backend };
+    const body = { name, model, engine: backend };
     if (backend === "claude") body.tools = [{ type: "agent_toolset_20260401" }];
     await api("/v1/agents", { method: "POST", body: JSON.stringify(body) });
     const a = await api("/v1/agents?limit=50");
     agents = a.data || [];
-    onboardBackend = backend;
+    onboardEngine = backend;
     onboardingStep = 1; // → environment step
     renderOnboarding();
     showToast("Agent created");
@@ -814,7 +825,7 @@ function renderAgents() {
   if (!agents.length) { el.innerHTML = '<p style="color:var(--dim);font-size:12px;padding:8px">No agents yet</p>'; return; }
   el.innerHTML = agents.map((a) => \`
     <div class="card-item">
-      <div><div class="name">\${esc(a.name)}</div><div class="detail">\${esc(a.model)} / \${a.backend}</div></div>
+      <div><div class="name">\${esc(a.name)}</div><div class="detail">\${esc(a.model)} / \${a.engine}</div></div>
       <div style="display:flex;gap:4px">
         <button class="btn btn-sm btn-secondary" onclick="showAgentConfig('\${esc(a.id)}')">Config</button>
         <button class="btn btn-sm btn-danger" onclick="deleteAgent('\${esc(a.id)}')">Delete</button>
@@ -890,8 +901,8 @@ function showCreateAgentModal() {
     <div class="modal">
       <h2>Create Agent</h2>
       <div class="form-group"><label class="form-label">Name</label><input class="form-input" id="agentName" value="Coder" /></div>
-      <div class="form-group"><label class="form-label">Backend</label>
-        <select class="form-select" id="agentBackend" onchange="updateModelOptions()">
+      <div class="form-group"><label class="form-label">Engine</label>
+        <select class="form-select" id="agentEngine" onchange="updateModelOptions()">
           <option value="claude">Claude</option><option value="opencode">OpenCode</option><option value="codex">Codex</option><option value="gemini">Gemini</option><option value="factory">Factory</option>
         </select>
       </div>
@@ -906,18 +917,18 @@ function showCreateAgentModal() {
 }
 
 function updateModelOptions() {
-  const backend = document.getElementById("agentBackend").value;
+  const backend = document.getElementById("agentEngine").value;
   const models = MODELS[backend] || MODELS.claude;
   document.getElementById("agentModel").innerHTML = models.map((m) => \`<option value="\${m}">\${m}</option>\`).join("");
 }
 
 async function createAgent() {
   const name = document.getElementById("agentName").value.trim();
-  const backend = document.getElementById("agentBackend").value;
+  const backend = document.getElementById("agentEngine").value;
   const model = document.getElementById("agentModel").value;
   if (!name) return;
   try {
-    const body = { name, model, backend };
+    const body = { name, model, engine: backend };
     if (backend === "claude") body.tools = [{ type: "agent_toolset_20260401" }];
     await api("/v1/agents", { method: "POST", body: JSON.stringify(body) });
     closeModal(); loadResources(); showToast("Agent created");
@@ -936,14 +947,20 @@ function showCreateEnvModal() {
       <div class="form-group"><label class="form-label">Name</label><input class="form-input" id="envName" value="dev" style="width:100%" /></div>
       <div class="form-group"><label class="form-label">Provider</label>
         <select class="form-select" id="envProvider" onchange="toggleEnvToken()" style="width:100%">
-          <option value="docker">Docker — Local containers</option>
-          <option value="sprites">sprites.dev — Cloud containers</option>
-          <option value="apple">Apple Containers — macOS 26+</option>
-          <option value="e2b">E2B — AI sandboxes</option>
-          <option value="vercel">Vercel Sandbox — Firecracker VMs</option>
-          <option value="daytona">Daytona — Dev environments</option>
-          <option value="fly">Fly.io — Global VMs</option>
-          <option value="modal">Modal — Serverless containers</option>
+          <optgroup label="Local">
+            <option value="docker">Docker</option>
+            <option value="apple-container">Apple Container (macOS 26+)</option>
+            <option value="apple-firecracker">AgentStep Firecracker microVM (M3+)</option>
+            <option value="podman">Podman</option>
+          </optgroup>
+          <optgroup label="Cloud">
+            <option value="sprites">sprites.dev</option>
+            <option value="e2b">E2B</option>
+            <option value="fly">Fly.io</option>
+            <option value="vercel">Vercel</option>
+            <option value="daytona">Daytona</option>
+            <option value="modal">Modal</option>
+          </optgroup>
         </select>
       </div>
       <div class="form-group" id="envTokenGroup" style="display:none">
@@ -1262,7 +1279,7 @@ function renderMarkdown(text) {
 </body>
 </html>
 `;
-const UI_VERSION = "77929c44";
+const UI_VERSION = "5c61307a";
 
 export async function handleGetUI(opts?: { apiKey?: string }): Promise<Response> {
   const inject = opts?.apiKey

package/src/openapi/schemas.ts

@@ -117,9 +117,9 @@ export const AgentSchema = registry.register(
     system: z.string().nullable(),
     tools: z.array(ToolConfigSchema),
     mcp_servers: z.record(McpServerConfigSchema),
-    backend: z.enum(["claude", "opencode", "codex", "anthropic", "gemini", "factory"]).openapi({
+    engine: z.enum(["claude", "opencode", "codex", "anthropic", "gemini", "factory"]).openapi({
       description:
-        "Which CLI engine powers this agent. `claude` drives `claude -p`; `opencode` drives sst/opencode-ai's `opencode run`; `gemini` drives Google's `gemini -p`; `factory` drives Factory's `droid exec`. Immutable after agent creation.",
+        "Which agent harness powers this agent. `claude` drives `claude -p`; `opencode` drives sst/opencode-ai's `opencode run`; `gemini` drives Google's `gemini -p`; `factory` drives Factory's `droid exec`. Immutable after agent creation.",
     }),
     webhook_url: z.string().nullable().openapi({
       description: "URL to POST webhook notifications to. Best-effort delivery with 5s timeout.",
@@ -147,9 +147,9 @@ export const CreateAgentRequestSchema = registry.register(
       system: z.string().nullish().openapi({ example: "You are a helpful assistant." }),
       tools: z.array(ToolConfigSchema).optional(),
       mcp_servers: z.record(McpServerConfigSchema).optional(),
-      backend: z.enum(["claude", "opencode", "codex", "anthropic", "gemini", "factory"]).optional().openapi({
+      engine: z.enum(["claude", "opencode", "codex", "anthropic", "gemini", "factory"]).optional().openapi({
         description:
-          "Backend CLI engine. Defaults to `claude`. Opencode agents must set `model` to a `provider/model` string (e.g. `anthropic/claude-sonnet-4-6`) and must NOT declare `tools` — opencode manages its tool surface internally. Gemini agents require GEMINI_API_KEY. Factory agents require FACTORY_API_KEY.",
+          "Agent harness. Defaults to `claude`. Opencode agents must set `model` to a `provider/model` string (e.g. `anthropic/claude-sonnet-4-6`) and must NOT declare `tools` — opencode manages its tool surface internally. Gemini agents require GEMINI_API_KEY. Factory agents require FACTORY_API_KEY.",
         example: "claude",
       }),
       webhook_url: z.string().url().optional().openapi({
@@ -218,9 +218,9 @@ export const EnvironmentConfigSchema = registry.register(
   "EnvironmentConfig",
   z.object({
     type: z.literal("cloud"),
-    provider: z.enum(["sprites", "docker", "apple", "podman", "e2b", "vercel", "daytona", "fly", "modal"]).optional().openapi({
+    provider: z.enum(["sprites", "docker", "apple-container", "apple-firecracker", "podman", "e2b", "vercel", "daytona", "fly", "modal"]).optional().openapi({
       description:
-        "Container provider for this environment. `sprites` uses sprites.dev cloud containers (default); `docker` uses local Docker containers; `apple` uses Apple Containers on macOS 26+ (Apple Silicon only); `podman` uses Podman containers; `e2b` uses E2B cloud sandboxes; `vercel` uses Vercel Sandboxes; `daytona` uses Daytona workspaces; `fly` uses Fly.io Machines; `modal` uses Modal sandboxes.",
+        "Container provider for this environment. `sprites` uses sprites.dev cloud containers (default); `docker` uses local Docker containers; `apple-container` uses Apple Containers on macOS 26+ (Apple Silicon only); `apple-firecracker` uses AgentStep Firecracker microVMs (macOS, M3+ Apple Silicon); `podman` uses Podman containers; `e2b` uses E2B cloud sandboxes; `vercel` uses Vercel Sandboxes; `daytona` uses Daytona workspaces; `fly` uses Fly.io Machines; `modal` uses Modal sandboxes.",
     }),
     packages: EnvironmentPackages.optional(),
     networking: EnvironmentNetworking.optional(),

package/src/providers/{apple.ts → apple-container.ts}

@@ -165,7 +165,7 @@ function containerExecStreaming(
 // ---------------------------------------------------------------------------
 
 export const appleProvider: ContainerProvider = {
-  name: "apple",
+  name: "apple-container",
   stripControlChars: false,
 
   async checkAvailability() {

package/src/providers/apple-firecracker.ts

@@ -0,0 +1,212 @@
+/**
+ * mvm (AgentStep Machines) provider.
+ *
+ * Runs CLI backends inside hardware-isolated Firecracker microVMs via mvm.
+ * Each session gets its own VM with a separate Linux kernel — stronger
+ * isolation than Docker (shared kernel) or Apple Containers (shared VZ).
+ *
+ * Requires mvm to be installed: `brew install agentstep/tap/mvm` or
+ * `npm install -g @agentstep/mvm`.
+ *
+ * VM lifecycle:
+ *   create → mvm start {name}
+ *   exec   → mvm exec {name} -- {argv}
+ *   delete → mvm delete {name} --force
+ *
+ * Features beyond Docker:
+ *   - Hardware isolation via KVM (separate kernel per VM)
+ *   - Network sandboxing (--net-policy deny)
+ *   - Pause/resume with full memory state
+ *   - Pre-installed AI agents (Claude Code, Codex, Gemini, OpenCode)
+ */
+import { spawn } from "node:child_process";
+import { Readable } from "node:stream";
+import type { ContainerProvider, ExecOptions, ExecSession } from "./types";
+
+import { execSync } from "node:child_process";
+
+// Use native mvm if available, otherwise npx
+let CLI = "mvm";
+try {
+  execSync("which mvm", { stdio: "ignore" });
+} catch {
+  CLI = "npx";
+}
+const CLI_ARGS: string[] = CLI === "npx" ? ["--yes", "@agentstep/mvm"] : [];
+
+function mvmRun(
+  args: string[],
+  opts?: { stdin?: string; timeoutMs?: number },
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(CLI, [...CLI_ARGS, ...args], { stdio: ["pipe", "pipe", "pipe"] });
+
+    let stdout = "";
+    let stderr = "";
+    proc.stdout?.on("data", (buf: Buffer) => { stdout += buf.toString(); });
+    proc.stderr?.on("data", (buf: Buffer) => { stderr += buf.toString(); });
+
+    if (opts?.stdin) {
+      proc.stdin?.write(opts.stdin);
+    }
+    proc.stdin?.end();
+
+    const timer = opts?.timeoutMs
+      ? setTimeout(() => {
+          proc.kill("SIGKILL");
+          reject(new Error(`mvm command timed out after ${opts.timeoutMs}ms`));
+        }, opts.timeoutMs)
+      : null;
+
+    proc.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`mvm ${args[0]} failed (${code}): ${stderr.trim()}`));
+      } else {
+        resolve(stdout);
+      }
+    });
+
+    proc.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+async function mvmExecOneShot(
+  vmName: string,
+  argv: string[],
+  stdin?: string,
+  timeoutMs?: number,
+): Promise<{ stdout: string; stderr: string; exit_code: number }> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(CLI, [...CLI_ARGS, "exec", vmName, "--", ...argv], {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    proc.stdout?.on("data", (buf: Buffer) => { stdout += buf.toString(); });
+    proc.stderr?.on("data", (buf: Buffer) => { stderr += buf.toString(); });
+
+    if (stdin) proc.stdin?.write(stdin);
+    proc.stdin?.end();
+
+    const timer = timeoutMs
+      ? setTimeout(() => {
+          proc.kill("SIGKILL");
+          reject(new Error(`mvm exec timed out after ${timeoutMs}ms`));
+        }, timeoutMs)
+      : null;
+
+    proc.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      resolve({ stdout, stderr, exit_code: code ?? 1 });
+    });
+
+    proc.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+function mvmExecStreaming(vmName: string, opts: ExecOptions): ExecSession {
+  const proc = spawn(CLI, [...CLI_ARGS, "exec", vmName, "--", ...opts.argv], {
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  if (opts.stdin) proc.stdin?.write(opts.stdin);
+  proc.stdin?.end();
+
+  const stdout = Readable.toWeb(proc.stdout!) as ReadableStream<Uint8Array>;
+
+  let exitResolve: (v: { code: number }) => void;
+  let exitReject: (e: unknown) => void;
+  const exit = new Promise<{ code: number }>((res, rej) => {
+    exitResolve = res;
+    exitReject = rej;
+  });
+
+  proc.on("close", (code) => exitResolve({ code: code ?? 0 }));
+  proc.on("error", (err) => exitReject(err));
+
+  let timer: NodeJS.Timeout | null = null;
+  if (opts.timeoutMs) {
+    timer = setTimeout(() => {
+      proc.kill("SIGKILL");
+      exitReject(new Error(`mvm exec timed out after ${opts.timeoutMs}ms`));
+    }, opts.timeoutMs);
+  }
+  exit.finally(() => { if (timer) clearTimeout(timer); });
+
+  if (opts.signal) {
+    if (opts.signal.aborted) {
+      proc.kill("SIGTERM");
+    } else {
+      opts.signal.addEventListener("abort", () => {
+        proc.kill("SIGTERM");
+        setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 3000);
+      });
+    }
+  }
+
+  return {
+    stdout,
+    exit,
+    async kill() {
+      proc.kill("SIGTERM");
+      setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 3000);
+    },
+  };
+}
+
+const NET_POLICY = process.env.MVM_NET_POLICY ?? "deny";
+
+export const mvmProvider: ContainerProvider = {
+  name: "apple-firecracker",
+  stripControlChars: false,
+
+  async checkAvailability() {
+    try {
+      await mvmRun(["version"], { timeoutMs: 30_000 });
+      return { available: true };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("ENOENT")) {
+        return { available: false, message: "mvm is not installed. Install via: npm install -g @agentstep/mvm" };
+      }
+      return { available: false, message: `mvm is not available: ${msg}` };
+    }
+  },
+
+  async create({ name }) {
+    // Clean up any existing VM with this name
+    await mvmRun(["delete", name, "--force"]).catch(() => {});
+    await mvmRun(["start", name, "--net-policy", NET_POLICY], { timeoutMs: 180_000 });
+  },
+
+  async delete(name) {
+    await mvmRun(["delete", name, "--force"]).catch(() => {});
+  },
+
+  async list(opts) {
+    try {
+      const out = await mvmRun(["list", "--json"]);
+      const vms = JSON.parse(out) as { name: string }[];
+      const prefix = opts?.prefix ?? "ca-sess-";
+      return vms.filter((v) => v.name.startsWith(prefix)).map((v) => ({ name: v.name }));
+    } catch {
+      return [];
+    }
+  },
+
+  async exec(name, argv, opts) {
+    return mvmExecOneShot(name, argv, opts?.stdin, opts?.timeoutMs);
+  },
+
+  startExec(name, opts) {
+    return Promise.resolve(mvmExecStreaming(name, opts));
+  },
+};

package/src/providers/registry.ts

@@ -10,7 +10,8 @@ import type { ContainerProvider, ProviderName } from "./types";
 const PROVIDERS: Record<ProviderName, () => Promise<ContainerProvider>> = {
   sprites: async () => (await import("./sprites")).spritesProvider,
   docker: async () => (await import("./docker")).dockerProvider,
-  apple: async () => (await import("./apple")).appleProvider,
+  "apple-container": async () => (await import("./apple-container")).appleProvider,
+  "apple-firecracker": async () => (await import("./apple-firecracker")).mvmProvider,
   podman: async () => (await import("./podman")).podmanProvider,
   e2b: async () => (await import("./e2b")).e2bProvider,
   vercel: async () => (await import("./vercel")).vercelProvider,

package/src/providers/types.ts

@@ -7,7 +7,7 @@
  * is selected per-environment via `EnvironmentConfig.provider`.
  */
 
-export type ProviderName = "sprites" | "docker" | "apple" | "podman" | "e2b" | "vercel" | "daytona" | "fly" | "modal";
+export type ProviderName = "sprites" | "docker" | "apple-container" | "apple-firecracker" | "podman" | "e2b" | "vercel" | "daytona" | "fly" | "modal";
 
 export interface ExecOptions {
   argv: string[];

package/src/sessions/driver.ts

@@ -79,7 +79,7 @@ export async function runTurn(
     return;
   }
 
-  const backend = resolveBackend(agent.backend);
+  const backend = resolveBackend(agent.engine);
 
   // Belt-and-braces runtime validation. Config may have changed since the
   // agent was created (env vars cleared, settings table mutated). Fail fast
@@ -275,7 +275,7 @@ export async function runTurn(
 
   // Tool bridge: if this is a custom tool result re-entry on claude backend,
   // write response.json and remove the pending sentinel before --resume.
-  if (agent.backend === "claude" && toolResults.length > 0) {
+  if (agent.engine === "claude" && toolResults.length > 0) {
     const { TOOL_BRIDGE_RESPONSE_PATH, TOOL_BRIDGE_PENDING_PATH } = await import("../backends/claude/tool-bridge");
     const spriteName = getSessionRow(sessionId)?.sprite_name;
     if (spriteName) {

package/src/sprite/lifecycle.ts

@@ -74,7 +74,7 @@ export async function acquireForFirstTurn(sessionId: string): Promise<string> {
   if (!agent) {
     throw new ApiError(404, "not_found_error", "agent not found for session");
   }
-  const backend = resolveBackend(agent.backend);
+  const backend = resolveBackend(agent.engine);
 
   // Resolve the container provider from the environment config.
   // Defaults to "sprites" for backward compatibility.
@@ -110,7 +110,7 @@ export async function acquireForFirstTurn(sessionId: string): Promise<string> {
     await backend.prepareOnSprite(name, provider);
 
     // Install custom tool bridge if the agent has custom tools or threads_enabled (claude backend only)
-    if (agent.backend === "claude") {
+    if (agent.engine === "claude") {
       const customTools = agent.tools.filter(
         (t): t is import("../types").CustomTool => t.type === "custom",
       );

package/src/types.ts

@@ -57,6 +57,8 @@ export interface McpServerConfig {
  * the backend registry.
  */
 export type BackendName = "claude" | "opencode" | "codex" | "anthropic" | "gemini" | "factory";
+/** API-facing alias for BackendName. */
+export type EngineName = BackendName;
 
 export interface AgentRow {
   id: string;
@@ -91,7 +93,7 @@ export interface Agent {
   system: string | null;
   tools: ToolConfig[];
   mcp_servers: Record<string, McpServerConfig>;
-  backend: BackendName;
+  engine: EngineName;
   webhook_url: string | null;
   webhook_events: string[];
   threads_enabled: boolean;
@@ -109,7 +111,7 @@ export type EnvironmentState = "preparing" | "ready" | "failed";
 
 export interface EnvironmentConfig {
   type: "cloud";
-  provider?: "sprites" | "docker" | "apple" | "podman" | "e2b" | "vercel" | "daytona" | "fly" | "modal";
+  provider?: "sprites" | "docker" | "apple-container" | "apple-firecracker" | "podman" | "e2b" | "vercel" | "daytona" | "fly" | "modal";
   packages?: {
     apt?: string[];
     cargo?: string[];