@an-sdk/cli 0.0.8 → 0.0.10

package/AGENTS.md

@@ -0,0 +1,19 @@
+# @an-sdk/cli
+
+CLI tool for deploying AI agents to the AN platform. Two commands: `an login` and `an deploy`.
+
+## Docs
+
+Full documentation: `./docs/` directory (8 guides covering the entire AN platform).
+
+## Source
+
+Source code: `./src/` directory.
+
+## Key Entry Points
+
+- `src/index.ts` — Command router (dispatches to login/deploy)
+- `src/login.ts` — API key auth flow, saves to `~/.an/credentials`
+- `src/deploy.ts` — Bundles agent code with esbuild, deploys to AN platform
+- `src/config.ts` — Reads/writes credentials and project config
+- `src/bundler.ts` — esbuild wrapper (externalizes `@an-sdk/agent`)

package/dist/index.js

@@ -9,7 +9,6 @@ import { join } from "path";
 import { homedir } from "os";
 var AN_DIR = join(homedir(), ".an");
 var CREDENTIALS_PATH = join(AN_DIR, "credentials");
-var PROJECT_PATH = join(process.cwd(), ".an", "project.json");
 function getApiKey() {
   if (process.env.AN_API_KEY) return process.env.AN_API_KEY;
   try {
@@ -23,24 +22,45 @@ function saveApiKey(apiKey) {
   mkdirSync(AN_DIR, { recursive: true });
   writeFileSync(CREDENTIALS_PATH, JSON.stringify({ apiKey }, null, 2));
 }
-function getProject() {
-  try {
-    const data = JSON.parse(readFileSync(PROJECT_PATH, "utf-8"));
-    if (data.projectId && data.projectSlug) return data;
-    if (data.slug) return { projectId: data.agentId ?? "", projectSlug: data.slug };
-    return null;
-  } catch {
-    return null;
-  }
+
+// src/detect.ts
+function isAgent() {
+  return !!(process.env.CLAUDE_CODE || process.env.CLAUDECODE || process.env.CURSOR_TRACE_ID || process.env.CURSOR_AGENT || process.env.CODEX_SANDBOX || process.env.GEMINI_CLI || process.env.AI_AGENT);
 }
-function saveProject(data) {
-  mkdirSync(join(process.cwd(), ".an"), { recursive: true });
-  writeFileSync(PROJECT_PATH, JSON.stringify(data, null, 2));
+function isInteractive() {
+  return !!process.stdin.isTTY && !isAgent();
 }
 
 // src/login.ts
 var API_BASE = process.env.AN_API_URL || "https://an.dev/api/v1";
-async function login() {
+async function verifyKey(apiKey) {
+  const res = await fetch(`${API_BASE}/me`, {
+    headers: { Authorization: `Bearer ${apiKey.trim()}` }
+  });
+  if (!res.ok) {
+    throw new Error("Invalid API key");
+  }
+  return res.json();
+}
+async function login(opts) {
+  const key = opts?.apiKey;
+  if (key) {
+    try {
+      const { user, team } = await verifyKey(key);
+      saveApiKey(key.trim());
+      console.log(`Authenticated as ${user.displayName || user.email} (team: ${team.name})`);
+      console.log("Key saved to ~/.an/credentials");
+    } catch {
+      console.error("Error: Invalid API key. Get a new one at https://an.dev/api-keys");
+      process.exit(1);
+    }
+    return;
+  }
+  if (!isInteractive()) {
+    console.error("Error: No API key provided. Use --api-key KEY or set AN_API_KEY env var.");
+    console.error("Get your API key at https://an.dev/api-keys");
+    process.exit(1);
+  }
   p.intro("an login");
   const existing = getApiKey();
   if (existing) {
@@ -59,39 +79,37 @@ async function login() {
   }
   const s = p.spinner();
   s.start("Verifying API key...");
-  const res = await fetch(`${API_BASE}/me`, {
-    headers: { Authorization: `Bearer ${apiKey.trim()}` }
-  });
-  if (!res.ok) {
+  try {
+    const { user, team } = await verifyKey(apiKey);
+    saveApiKey(apiKey.trim());
+    s.stop("Verified");
+    p.log.success(`Authenticated as ${user.displayName || user.email} (team: ${team.name})`);
+    p.log.info("Key saved to ~/.an/credentials");
+    p.outro("Done");
+  } catch {
     s.stop("Invalid API key");
     p.log.error("Invalid API key. Get a new one at https://an.dev/api-keys");
     process.exit(1);
   }
-  const { user, team } = await res.json();
-  saveApiKey(apiKey.trim());
-  s.stop("Verified");
-  p.log.success(`Authenticated as ${user.displayName || user.email} (team: ${team.name})`);
-  p.log.info("Key saved to ~/.an/credentials");
-  p.outro("Done");
 }
 
 // src/bundler.ts
 import esbuild from "esbuild";
 async function findAgentEntryPoints() {
-  const { existsSync, readdirSync, statSync } = await import("fs");
-  const { join: join2, basename: basename2, extname } = await import("path");
-  if (!existsSync("agents") || !statSync("agents").isDirectory()) {
+  const { existsSync: existsSync2, readdirSync, statSync } = await import("fs");
+  const { join: join3, basename, extname } = await import("path");
+  if (!existsSync2("agents") || !statSync("agents").isDirectory()) {
     throw new Error("No agents/ directory found. See https://an.dev/docs to get started.");
   }
   const entries = [];
   const items = readdirSync("agents");
   for (const item of items) {
-    const fullPath = join2("agents", item);
+    const fullPath = join3("agents", item);
     const stat = statSync(fullPath);
     if (stat.isDirectory()) {
       for (const indexFile of ["index.ts", "index.js"]) {
-        const indexPath = join2(fullPath, indexFile);
-        if (existsSync(indexPath)) {
+        const indexPath = join3(fullPath, indexFile);
+        if (existsSync2(indexPath)) {
           entries.push({ slug: item, entryPoint: indexPath });
           break;
         }
@@ -99,7 +117,7 @@ async function findAgentEntryPoints() {
     } else if (stat.isFile()) {
       const ext = extname(item);
       if (ext === ".ts" || ext === ".js") {
-        entries.push({ slug: basename2(item, ext), entryPoint: fullPath });
+        entries.push({ slug: basename(item, ext), entryPoint: fullPath });
       }
     }
   }
@@ -128,64 +146,86 @@ ${result.errors.map((e) => e.text).join("\n")}`
   }
   return Buffer.from(result.outputFiles[0].contents);
 }
-
-// src/deploy.ts
-import { basename } from "path";
-import * as p2 from "@clack/prompts";
-function slugify(name) {
-  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+async function importBundle(bundle) {
+  const { writeFileSync: writeFileSync2, unlinkSync, mkdirSync: mkdirSync2 } = await import("fs");
+  const { join: join3 } = await import("path");
+  const tmpDir = join3(process.cwd(), ".an-tmp");
+  mkdirSync2(tmpDir, { recursive: true });
+  const tmpPath = join3(tmpDir, `an-bundle-${Date.now()}.mjs`);
+  try {
+    writeFileSync2(tmpPath, bundle);
+    const mod = await import(tmpPath);
+    const config = mod.default;
+    if (config?._type === "agent") return config;
+    return null;
+  } catch {
+    return null;
+  } finally {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+    }
+    try {
+      const { rmdirSync } = await import("fs");
+      rmdirSync(tmpDir);
+    } catch {
+    }
+  }
 }
-var API_BASE2 = process.env.AN_API_URL || "https://an.dev/api/v1";
-var AN_BASE = process.env.AN_URL || "https://an.dev";
-async function fetchProjects(apiKey) {
-  const res = await fetch(`${API_BASE2}/projects`, {
-    headers: { Authorization: `Bearer ${apiKey}` }
-  });
-  if (!res.ok) return [];
-  const data = await res.json();
-  return data.projects ?? [];
+async function extractSandboxConfig(bundle) {
+  const config = await importBundle(bundle);
+  if (!config) return null;
+  const sandbox = config.sandbox;
+  if (sandbox && sandbox._type === "sandbox") {
+    const { _type, ...sandboxConfig } = sandbox;
+    return sandboxConfig;
+  }
+  return null;
 }
-async function linkProject(apiKey) {
-  const projects = await fetchProjects(apiKey);
-  if (projects.length === 0) {
-    const name = await p2.text({
-      message: "Project name",
-      defaultValue: basename(process.cwd()),
-      placeholder: basename(process.cwd())
-    });
-    if (p2.isCancel(name)) {
-      p2.cancel("Deploy cancelled.");
-      process.exit(0);
+var HOOK_NAMES = ["onStart", "onToolCall", "onToolResult", "onStepFinish", "onFinish", "onError"];
+async function extractAgentMetadata(bundle) {
+  try {
+    const config = await importBundle(bundle);
+    if (!config) return null;
+    const tools = [];
+    if (config.tools && typeof config.tools === "object") {
+      for (const [name, def] of Object.entries(config.tools)) {
+        tools.push({ name, description: def?.description ?? "" });
+      }
     }
-    return { projectId: "", projectSlug: slugify(name) };
-  }
-  const options = [
-    { value: "__new__", label: "Create a new project" },
-    ...projects.map((proj) => ({ value: proj.slug, label: proj.name || proj.slug }))
-  ];
-  const choice = await p2.select({
-    message: "Link to a project",
-    options
-  });
-  if (p2.isCancel(choice)) {
-    p2.cancel("Deploy cancelled.");
-    process.exit(0);
-  }
-  if (choice === "__new__") {
-    const name = await p2.text({
-      message: "Project name",
-      defaultValue: basename(process.cwd()),
-      placeholder: basename(process.cwd())
-    });
-    if (p2.isCancel(name)) {
-      p2.cancel("Deploy cancelled.");
-      process.exit(0);
+    const hooks = HOOK_NAMES.filter((h) => typeof config[h] === "function");
+    const metadata = {
+      model: config.model ?? "unknown",
+      permissionMode: config.permissionMode ?? "default",
+      maxTurns: config.maxTurns ?? 50,
+      tools,
+      hooks
+    };
+    if (config.systemPrompt !== void 0) {
+      metadata.systemPrompt = config.systemPrompt;
+    }
+    if (config.maxBudgetUsd !== void 0) {
+      metadata.maxBudgetUsd = config.maxBudgetUsd;
+    }
+    const sandbox = config.sandbox;
+    if (sandbox && sandbox._type === "sandbox") {
+      metadata.sandbox = {};
+      if (sandbox.apt) metadata.sandbox.apt = sandbox.apt;
+      if (sandbox.setup) metadata.sandbox.setup = sandbox.setup;
+      if (sandbox.cwd) metadata.sandbox.cwd = sandbox.cwd;
     }
-    return { projectId: "", projectSlug: slugify(name) };
+    return metadata;
+  } catch {
+    return null;
   }
-  const selected = projects.find((proj) => proj.slug === choice);
-  return { projectId: selected.id, projectSlug: selected.slug };
 }
+
+// src/deploy.ts
+import { existsSync } from "fs";
+import { join as join2 } from "path";
+import * as p2 from "@clack/prompts";
+var API_BASE2 = process.env.AN_API_URL || "https://an.dev/api/v1";
+var AN_BASE = process.env.AN_URL || "https://an.dev";
 async function deploy() {
   p2.intro("an deploy");
   const apiKey = getApiKey();
@@ -193,6 +233,9 @@ async function deploy() {
     p2.log.error("Not logged in. Run `an login` first, or set AN_API_KEY env var.");
     process.exit(1);
   }
+  if (existsSync(join2(process.cwd(), ".an", "project.json"))) {
+    p2.log.warn(".an/project.json is no longer used and can be removed.");
+  }
   let agents;
   try {
     agents = await findAgentEntryPoints();
@@ -201,25 +244,13 @@ async function deploy() {
     process.exit(1);
   }
   p2.log.info(`Found ${agents.length} agent${agents.length > 1 ? "s" : ""}`);
-  let project = getProject();
-  let projectSlug;
-  let projectId;
-  if (project) {
-    projectSlug = project.projectSlug;
-    projectId = project.projectId;
-  } else if (process.stdin.isTTY) {
-    const linked = await linkProject(apiKey);
-    projectSlug = linked.projectSlug;
-    projectId = linked.projectId;
-  } else {
-    projectSlug = slugify(basename(process.cwd()));
-    projectId = "";
-  }
   const deployed = [];
   for (const agent of agents) {
     const s = p2.spinner();
     s.start(`Bundling ${agent.slug}...`);
     const bundle = await bundleAgent(agent.entryPoint);
+    const sandboxConfig = await extractSandboxConfig(bundle);
+    const metadata = await extractAgentMetadata(bundle);
     s.stop(`Bundled ${agent.slug} (${(bundle.length / 1024).toFixed(1)}kb)`);
     const s2 = p2.spinner();
     s2.start(`Deploying ${agent.slug}...`);
@@ -230,9 +261,10 @@ async function deploy() {
         "Content-Type": "application/json"
       },
       body: JSON.stringify({
-        projectSlug,
         slug: agent.slug,
-        bundle: bundle.toString("base64")
+        bundle: bundle.toString("base64"),
+        ...sandboxConfig && { sandboxConfig },
+        ...metadata && { metadata }
       })
     });
     if (!res.ok) {
@@ -243,22 +275,20 @@ async function deploy() {
         p2.log.info(`
 Deployed before failure:`);
         for (const a of deployed) {
-          p2.log.info(`  ${a.slug}  \u2192  ${AN_BASE}/a/${projectSlug}/${a.slug}`);
+          p2.log.info(`  ${a.slug}  \u2192  ${AN_BASE}/a/${a.slug}`);
         }
       }
       process.exit(1);
     }
     const result = await res.json();
-    projectId = result.projectId;
-    projectSlug = result.projectSlug;
     deployed.push({ slug: agent.slug });
-    s2.stop(`${agent.slug} deployed`);
+    const versionTag = result.version ? ` (v${result.version})` : "";
+    s2.stop(`${agent.slug} deployed${versionTag}`);
   }
-  saveProject({ projectId, projectSlug });
-  p2.log.success(`Deployed ${deployed.length} agent${deployed.length > 1 ? "s" : ""} to ${projectSlug}`);
+  p2.log.success(`Deployed ${deployed.length} agent${deployed.length > 1 ? "s" : ""}`);
   console.log();
   for (const agent of deployed) {
-    console.log(`  ${agent.slug}  \u2192  ${AN_BASE}/a/${projectSlug}/${agent.slug}`);
+    console.log(`  ${agent.slug}  \u2192  ${AN_BASE}/a/${agent.slug}`);
   }
   console.log();
   p2.log.info("Next steps:");
@@ -268,6 +298,125 @@ Deployed before failure:`);
   p2.outro("Done");
 }
 
+// src/env.ts
+import * as p3 from "@clack/prompts";
+var API_BASE3 = process.env.AN_API_URL || "https://an.dev/api/v1";
+function maskValue(value) {
+  if (value.length <= 4) return "\u2022".repeat(value.length);
+  return value.slice(0, 2) + "\u2022".repeat(Math.min(value.length - 4, 12)) + value.slice(-2);
+}
+function requireAuth() {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    p3.log.error("Not logged in. Run `an login` first, or set AN_API_KEY env var.");
+    process.exit(1);
+  }
+  return apiKey;
+}
+function requireAgentSlug(args2) {
+  const slug = args2[0];
+  if (!slug || slug.startsWith("-")) {
+    p3.log.error("Agent slug is required. Usage: an env list <agent-slug>");
+    process.exit(1);
+  }
+  return slug;
+}
+async function fetchEnvVars(apiKey, agentSlug) {
+  const res = await fetch(`${API_BASE3}/agents/${agentSlug}/env`, {
+    headers: { Authorization: `Bearer ${apiKey}` }
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err.message || `Failed to fetch env vars (${res.status})`);
+  }
+  const data = await res.json();
+  return data.envVars ?? {};
+}
+async function putEnvVars(apiKey, agentSlug, envVars) {
+  const res = await fetch(`${API_BASE3}/agents/${agentSlug}/env`, {
+    method: "PUT",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ envVars })
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err.message || `Failed to update env vars (${res.status})`);
+  }
+}
+async function envList(args2) {
+  const apiKey = requireAuth();
+  const agentSlug = requireAgentSlug(args2);
+  const showValues = args2.includes("--show-values");
+  try {
+    const vars = await fetchEnvVars(apiKey, agentSlug);
+    const keys = Object.keys(vars);
+    if (keys.length === 0) {
+      p3.log.info("No environment variables set.");
+      return;
+    }
+    console.log();
+    for (const key of keys) {
+      const display = showValues ? vars[key] : maskValue(vars[key]);
+      console.log(`  ${key}=${display}`);
+    }
+    console.log();
+    p3.log.info(`${keys.length} variable${keys.length !== 1 ? "s" : ""}`);
+  } catch (err) {
+    p3.log.error(err.message);
+    process.exit(1);
+  }
+}
+async function envSet(args2) {
+  const apiKey = requireAuth();
+  const agentSlug = requireAgentSlug(args2);
+  const key = args2[1];
+  const value = args2.slice(2).join(" ");
+  if (!key || !value) {
+    p3.log.error("Usage: an env set <agent-slug> KEY VALUE");
+    process.exit(1);
+  }
+  if (!/^[A-Z0-9_]+$/.test(key)) {
+    p3.log.error("Invalid key. Use uppercase letters, numbers, and underscores only.");
+    process.exit(1);
+  }
+  try {
+    const vars = await fetchEnvVars(apiKey, agentSlug);
+    const existed = key in vars;
+    vars[key] = value;
+    await putEnvVars(apiKey, agentSlug, vars);
+    p3.log.success(existed ? `Updated ${key}` : `Set ${key}`);
+  } catch (err) {
+    p3.log.error(err.message);
+    process.exit(1);
+  }
+}
+async function envRemove(args2) {
+  const apiKey = requireAuth();
+  const agentSlug = requireAgentSlug(args2);
+  const key = args2[1];
+  if (!key) {
+    p3.log.error("Usage: an env remove <agent-slug> KEY");
+    process.exit(1);
+  }
+  try {
+    const vars = await fetchEnvVars(apiKey, agentSlug);
+    if (!(key in vars)) {
+      p3.log.info(`${key} not found`);
+      return;
+    }
+    delete vars[key];
+    const envVars = Object.keys(vars).length > 0 ? vars : null;
+    await putEnvVars(apiKey, agentSlug, envVars);
+    p3.log.success(`Removed ${key}`);
+  } catch (err) {
+    p3.log.error(err.message);
+    process.exit(1);
+  }
+}
+
 // src/index.ts
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
@@ -275,23 +424,36 @@ var { version } = require2("../package.json");
 var command = process.argv[2];
 var args = process.argv.slice(3);
 var hasFlag = (flag) => args.includes(flag);
+function getFlagValue(flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return void 0;
+  return args[idx + 1];
+}
 function showHelp() {
   console.log(`AN CLI v${version} \u2014 deploy AI agents
 `);
   console.log("Usage: an <command>\n");
   console.log("Commands:");
-  console.log("  an login      Authenticate with AN platform");
-  console.log("  an deploy     Bundle and deploy your agent");
+  console.log("  an login                  Authenticate with AN platform");
+  console.log("  an deploy                 Bundle and deploy your agent");
+  console.log("  an env list <agent>       List environment variables");
+  console.log("  an env set <agent> K V    Set an environment variable");
+  console.log("  an env remove <agent> K   Remove an environment variable");
   console.log("\nOptions:");
-  console.log("  --help, -h    Show help");
-  console.log("  --version, -v Show version");
+  console.log("  --help, -h              Show help");
+  console.log("  --version, -v           Show version");
+  console.log("\nEnvironment variables:");
+  console.log("  AN_API_KEY              API key (skips login prompt)");
+  console.log("  AN_API_URL              API base URL override");
   console.log("\nGet started: an login");
   console.log("Docs: https://an.dev/docs");
 }
 function showLoginHelp() {
-  console.log("Usage: an login\n");
-  console.log("Authenticate with the AN platform using an API key.");
-  console.log("Get your API key at https://an.dev/api-keys");
+  console.log("Usage: an login [options]\n");
+  console.log("Authenticate with the AN platform using an API key.\n");
+  console.log("Options:");
+  console.log("  --api-key KEY    Pass API key directly (non-interactive)");
+  console.log("\nGet your API key at https://an.dev/api-keys");
 }
 function showDeployHelp() {
   console.log("Usage: an deploy\n");
@@ -303,18 +465,45 @@ function showDeployHelp() {
   console.log("    another.ts       single-file agent");
   console.log("\nDocs: https://an.dev/docs");
 }
+function showEnvHelp() {
+  console.log("Usage: an env <subcommand> <agent-slug>\n");
+  console.log("Manage environment variables for an agent.\n");
+  console.log("Subcommands:");
+  console.log("  an env list <agent>              List all env vars (masked)");
+  console.log("  an env list <agent> --show-values List all env vars (plain text)");
+  console.log("  an env set <agent> KEY VALUE     Set or update an env var");
+  console.log("  an env remove <agent> KEY        Remove an env var");
+}
 if (command === "login") {
   if (hasFlag("--help") || hasFlag("-h")) {
     showLoginHelp();
   } else {
-    await login();
+    await login({ apiKey: getFlagValue("--api-key") });
   }
 } else if (command === "deploy") {
   if (hasFlag("--help") || hasFlag("-h")) {
     showDeployHelp();
   } else {
+    if (hasFlag("--project")) {
+      console.log("Warning: --project flag is no longer used and will be ignored.");
+    }
     await deploy();
   }
+} else if (command === "env") {
+  const subcommand = args[0];
+  const subArgs = args.slice(1);
+  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+    showEnvHelp();
+  } else if (subcommand === "list") {
+    await envList(subArgs);
+  } else if (subcommand === "set") {
+    await envSet(subArgs);
+  } else if (subcommand === "remove") {
+    await envRemove(subArgs);
+  } else {
+    console.log(`Unknown env subcommand: ${subcommand}`);
+    showEnvHelp();
+  }
 } else if (command === "--version" || command === "-v") {
   console.log(version);
 } else {

package/docs/01-overview.md

@@ -0,0 +1,61 @@
+# AN Platform Overview
+
+AN is a platform for building, deploying, and embedding AI agents. You define an agent in TypeScript, deploy it with one command, and embed a chat UI in any React app.
+
+## Architecture
+
+```
+Your Code (agent.ts)
+    |
+    v
+an deploy (CLI)
+    |
+    v
+AN Platform
+    |
+    +---> E2B Sandbox (isolated Node.js environment)
+    |         |
+    |         +---> Claude Agent SDK / Codex (executes your agent)
+    |         |
+    |         +---> Your custom tools run here
+    |
+    +---> AN Relay (relay.an.dev)
+              |
+              +---> SSE streaming to clients
+              |
+              +---> Token exchange (API key -> short-lived JWT)
+```
+
+## Packages
+
+| Package | Purpose |
+|---------|---------|
+| `@an-sdk/agent` | Define agents and tools with type inference |
+| `@an-sdk/cli` | Deploy agents from your terminal |
+| `@an-sdk/react` | Chat UI components (theming, tool renderers) |
+| `@an-sdk/nextjs` | Next.js server-side token handler |
+| `@an-sdk/node` | Server-side SDK (sandboxes, threads, tokens) |
+
+## Key Concepts
+
+- **Agent**: A TypeScript config defining model, system prompt, tools, and hooks. Runs in a cloud sandbox.
+- **Tool**: A function your agent can call, with a Zod schema for input validation and full type inference.
+- **Sandbox**: An isolated E2B cloud environment where your agent executes. Has Node.js, git, and system tools.
+- **Thread**: A conversation within a sandbox. One sandbox can have multiple threads.
+- **Relay**: The streaming gateway at `relay.an.dev`. Handles auth, routing, and SSE streaming.
+
+## Runtimes
+
+AN supports two runtimes:
+
+- **`claude-code`** (default) — Uses the Claude Agent SDK. Full tool use, file editing, bash execution.
+- **`codex`** — Uses OpenAI Codex via ACP provider.
+
+## Auth Model
+
+Two layers of authentication:
+
+1. **Client -> Relay**: API key (`an_sk_...`) or short-lived JWT (via token exchange)
+2. **Sandbox -> AI Provider**: Handled internally by the platform (Claude Proxy)
+
+For web apps, use `@an-sdk/nextjs` to exchange your API key for a short-lived JWT on the server, so the key never reaches the browser.