agent-neckbeard 0.0.5 → 1.0.0

package/README.md

@@ -1,177 +1,102 @@
-# agent-neckbeard
+<img width="1024" height="1024" alt="image" src="https://github.com/user-attachments/assets/52b7f9cf-b9c7-4cae-be11-62273cd1489a" />
 
-Deploy AI agents to E2B sandboxes with structured input/output validation.
+# neckbeard
 
-## The Problem
+There's a weird thing that happens when you try to deploy an AI agent.
 
-When building agentic workflows with the [Claude Agent SDK](https://github.com/anthropics/claude-code), the agent process needs to run **inside** a sandbox—not just the tool calls. This means:
+Most people think of agents as fancy API calls. You send a prompt, you get a response. But that's not what's actually happening. The agent is running code. It's executing bash commands, writing files, installing packages. It runs for minutes at a time, maintaining state between steps. It's a process, not a request.
 
-- The agent can execute bash commands, write files, and perform complex multi-step tasks
-- All execution is isolated and secure
-- The agent maintains conversation state across tool calls
+This creates an obvious problem: do you really want that process running on your production server?
 
-E2B provides sandboxed environments, but wiring up the deployment, bundling, and I/O is tedious. This package handles it for you.
+Anthropic's answer is no. Their [hosting docs](https://docs.claude.com/en/docs/agent-sdk/hosting) say you should run the entire agent inside a sandbox. Not just intercept the dangerous tool calls—put the whole thing in a container where it can't escape.
 
-## How It Works
+That sounds simple. It's not.
 
-1. **Define** an agent with typed input/output schemas
-2. **Deploy** bundles your code with esbuild and uploads to E2B
-3. **Run** writes input to `/input/task.json`, executes, reads from `/output/result.json`
+## The Plumbing Problem
+
+Sandboxes like E2B give you a fresh Linux container. Your agent code lives in your repo. Bridging these two worlds is surprisingly annoying.
+
+First, you have to get your code into the sandbox. You could bake it into a custom template, but then you're rebuilding templates every time you change a line. You could git clone on boot, but that's slow and requires auth. You could bundle and upload at runtime, which works, but now you're writing bundler configs.
+
+Then you have to pass input. How do you get the user's prompt into a process running inside a sandbox? CLI arguments require escaping and have length limits. Environment variables have size limits. Writing to a file works, but adds boilerplate.
+
+The worst part is output. When you run `sandbox.exec("node agent.js")`, you get back everything the process printed. SDK logs, debug output, streaming tokens, and somewhere in there, your actual result. Good luck parsing that reliably.
+
+So you end up writing results to a file, reading it back, parsing JSON, validating the shape, handling errors. Every team building sandboxed agents writes some version of this plumbing. It's tedious.
+
+## What This Does
+
+Neckbeard handles all of that so you can just write your agent:
 
 ```typescript
 import { Agent } from 'agent-neckbeard';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 
-const summaryAgent = new Agent({
+const agent = new Agent({
   id: 'summary',
-  maxDuration: 120,
-  inputSchema: z.object({
-    topic: z.string(),
-  }),
+  inputSchema: z.object({ topic: z.string() }),
   outputSchema: z.object({
     title: z.string(),
     summary: z.string(),
     keyPoints: z.array(z.string()),
   }),
-  run: async (input, ctx) => {
-    let result = { title: '', summary: '', keyPoints: [] as string[] };
-
+  run: async (input) => {
     for await (const message of query({
-      prompt: `Research "${input.topic}" and return JSON with title, summary, keyPoints`,
-      options: { maxTurns: 10, allowedTools: ['write', 'read'] },
-      abortSignal: ctx.signal,
+      prompt: `Research "${input.topic}" and return JSON`,
+      options: { maxTurns: 10 },
     })) {
       if (message.type === 'result') {
-        result = JSON.parse(message.result ?? '{}');
+        return JSON.parse(message.result ?? '{}');
       }
     }
-
-    return result;
   },
 });
 
-// Deploy once
-await summaryAgent.deploy();
-
-// Run many times
-const result = await summaryAgent.run({ topic: 'TypeScript generics' });
-console.log(result.title);      // string - validated
-console.log(result.keyPoints);  // string[] - validated
+await agent.deploy();  // bundles, uploads to E2B
+const result = await agent.run({ topic: 'TypeScript generics' });
 ```
 
-## Installation
+`deploy()` bundles your code with esbuild and uploads it. `run()` writes input to a file, executes, reads the result back, and validates it against your schema. You don't think about file paths or stdout parsing.
 
-```bash
-npm install agent-neckbeard
-```
-
-Set your API keys:
+## Setup
 
 ```bash
-export E2B_API_KEY=your-e2b-api-key
-export ANTHROPIC_API_KEY=your-anthropic-api-key  # Required for Claude Agent SDK
+npm install agent-neckbeard
 ```
 
-## Running Examples
-
 ```bash
-cd examples
-npm install
-npm run summary-agent
+export E2B_API_KEY=your-key
+export ANTHROPIC_API_KEY=your-key
 ```
 
-## API
+## The Details
 
-### `new Agent(config)`
+The constructor takes a few options:
 
 ```typescript
-const agent = new Agent({
-  id: string,                    // Unique identifier
-  inputSchema: ZodSchema,        // Validates input before run
-  outputSchema: ZodSchema,       // Validates output after run
-  run: (input, ctx) => Promise,  // Your agent logic
-  maxDuration?: number,          // Timeout in seconds (default: 300)
-  sandboxId?: string,            // Reuse existing sandbox (skip deploy)
-  dependencies?: {               // OS-level dependencies to install
-    apt?: string[],              // APT packages (e.g., ['curl', 'git'])
-    npm?: string[],              // Global npm packages
-    commands?: string[],         // Custom shell commands
+new Agent({
+  id: string,
+  inputSchema: ZodSchema,
+  outputSchema: ZodSchema,
+  run: (input, ctx) => Promise,
+  maxDuration?: number,        // seconds, default 300
+  sandboxId?: string,          // reuse existing sandbox
+  dependencies?: {
+    apt?: string[],
+    commands?: string[],
   },
-});
-```
-
-### `agent.deploy()`
-
-Bundles your agent code with esbuild and uploads to a new E2B sandbox. Automatically detects the source file—no entry point needed.
-
-```typescript
-await agent.deploy();
-console.log(agent.sandboxId);  // 'sandbox-abc123'
-```
-
-### `agent.run(input)`
-
-Executes the agent in the sandbox with validated input/output.
-
-```typescript
-const result = await agent.run({ topic: 'quantum computing' });
-// result is typed and validated against outputSchema
-```
-
-### Reusing a Sandbox
-
-If you already have a deployed sandbox, pass `sandboxId` to skip deployment:
-
-```typescript
-const agent = new Agent({
-  id: 'summary',
-  sandboxId: 'existing-sandbox-id',  // Skip deploy()
-  inputSchema,
-  outputSchema,
-  run,
-});
-
-// No deploy needed
-const result = await agent.run({ topic: 'hello' });
+  files?: [{ url, path }],     // pre-download into sandbox
+})
 ```
 
-## External Packages
+If you already have a sandbox deployed, pass `sandboxId` and skip `deploy()`.
 
-Some packages can't be bundled and need to be installed in the sandbox at runtime. These include packages that:
-- Spawn child processes (like `@anthropic-ai/claude-agent-sdk` which spawns its CLI)
-- Have native modules
+The `files` option downloads things into the sandbox before your agent runs—useful for models or config files. Relative paths resolve from `/home/user/`.
 
-These packages are automatically marked as external during bundling and installed via npm in the sandbox.
+Some packages can't be bundled because they spawn child processes or have native modules. The Claude Agent SDK is like this. These get automatically marked as external and installed via npm in the sandbox.
 
-```typescript
-import { query } from '@anthropic-ai/claude-agent-sdk';
-
-const agent = new Agent({
-  // ...
-  run: async (input, ctx) => {
-    for await (const message of query({
-      prompt: `Do something with ${input.topic}`,
-      options: { maxTurns: 10, allowedTools: ['Bash', 'Read', 'Write'] },
-    })) {
-      // Handle Claude's responses
-    }
-  },
-});
-```
-
-## Context
-
-The `run` function receives a context object:
-
-```typescript
-run: async (input, ctx) => {
-  ctx.executionId  // Unique ID for this execution
-  ctx.signal       // AbortSignal for cancellation
-  ctx.env          // Environment variables
-  ctx.logger       // { debug, info, warn, error }
-}
-```
+The `run` function gets a context object with an `executionId`, an `AbortSignal`, environment variables, and a logger.
 
 ## License
 

package/dist/index.d.ts

@@ -27,11 +27,24 @@ interface SchemaLike<T> {
 interface OsDependencies {
     /** APT packages to install (e.g., ['curl', 'git']) */
     apt?: string[];
-    /** NPM packages to install globally (e.g., ['typescript', '@anthropic-ai/claude-code']) */
-    npm?: string[];
     /** Custom shell commands to run during setup */
     commands?: string[];
 }
+/**
+ * Configuration for downloading a file into the sandbox filesystem.
+ * Files are downloaded during deploy() before the agent runs.
+ */
+interface FileDownload {
+    /** URL to download the file from (supports http/https) */
+    url: string;
+    /**
+     * Destination path in the sandbox.
+     * Can be absolute (e.g., '/home/user/data/model.bin') or
+     * relative to /home/user/ (e.g., 'data/model.bin').
+     * Parent directories are created automatically.
+     */
+    path: string;
+}
 /** Default dependencies - empty by default, specify what you need */
 declare const DEFAULT_DEPENDENCIES: OsDependencies;
 interface AgentConfig<TInput, TOutput> {
@@ -43,6 +56,12 @@ interface AgentConfig<TInput, TOutput> {
     sandboxId?: string;
     /** OS-level dependencies to install in the sandbox. Defaults to Claude Code. Set to {} to skip. */
     dependencies?: OsDependencies;
+    /**
+     * Files to download and initialize in the sandbox filesystem.
+     * Downloaded during deploy() before the agent code runs.
+     * Useful for pre-loading models, datasets, configuration files, etc.
+     */
+    files?: FileDownload[];
 }
 declare class Agent<TInput, TOutput> {
     readonly id: string;
@@ -50,6 +69,7 @@ declare class Agent<TInput, TOutput> {
     readonly outputSchema: SchemaLike<TOutput>;
     readonly maxDuration: number;
     readonly dependencies: OsDependencies;
+    readonly files: FileDownload[];
     /** @internal Used by the sandbox runner - must be public for bundled code access */
     _run: (input: TInput, ctx: AgentRunContext) => Promise<TOutput>;
     private _sourceFile;
@@ -60,4 +80,4 @@ declare class Agent<TInput, TOutput> {
     run(input: TInput): Promise<AgentRunResult<TOutput>>;
 }
 
-export { Agent, type AgentConfig, type AgentRunContext, type AgentRunResult, DEFAULT_DEPENDENCIES, type OsDependencies };
+export { Agent, type AgentConfig, type AgentRunContext, type AgentRunResult, DEFAULT_DEPENDENCIES, type FileDownload, type OsDependencies };

package/dist/index.js

@@ -21,6 +21,7 @@ var Agent = class {
   outputSchema;
   maxDuration;
   dependencies;
+  files;
   /** @internal Used by the sandbox runner - must be public for bundled code access */
   _run;
   _sourceFile;
@@ -34,6 +35,7 @@ var Agent = class {
     this._sourceFile = getCallerFile();
     this._sandboxId = config.sandboxId;
     this.dependencies = config.dependencies ?? DEFAULT_DEPENDENCIES;
+    this.files = config.files ?? [];
   }
   get sandboxId() {
     return this._sandboxId;
@@ -132,7 +134,7 @@ try {
     const sandbox = await Sandbox.create("base", {
       apiKey: process.env.E2B_API_KEY
     });
-    const { apt, npm, commands } = this.dependencies;
+    const { apt, commands } = this.dependencies;
     if (apt && apt.length > 0) {
       const aptCmd = `apt-get update && apt-get install -y ${apt.join(" ")}`;
       const aptResult = await sandbox.commands.run(aptCmd, { timeoutMs: 3e5 });
@@ -140,13 +142,6 @@ try {
         throw new Error(`Failed to install apt packages: ${aptResult.stderr}`);
       }
     }
-    if (npm && npm.length > 0) {
-      const npmCmd = `npm install -g ${npm.join(" ")}`;
-      const npmResult = await sandbox.commands.run(npmCmd, { timeoutMs: 3e5 });
-      if (npmResult.exitCode !== 0) {
-        throw new Error(`Failed to install npm packages: ${npmResult.stderr}`);
-      }
-    }
     if (commands && commands.length > 0) {
       for (const cmd of commands) {
         const cmdResult = await sandbox.commands.run(cmd, { timeoutMs: 3e5 });
@@ -155,6 +150,20 @@ try {
         }
       }
     }
+    if (this.files.length > 0) {
+      for (const file of this.files) {
+        const destPath = file.path.startsWith("/") ? file.path : `/home/user/${file.path}`;
+        const parentDir = destPath.substring(0, destPath.lastIndexOf("/"));
+        if (parentDir) {
+          await sandbox.commands.run(`mkdir -p "${parentDir}"`, { timeoutMs: 3e4 });
+        }
+        const curlCmd = `curl -fsSL -o "${destPath}" "${file.url}"`;
+        const downloadResult = await sandbox.commands.run(curlCmd, { timeoutMs: 3e5 });
+        if (downloadResult.exitCode !== 0) {
+          throw new Error(`Failed to download file from ${file.url} to ${destPath}: ${downloadResult.stderr}`);
+        }
+      }
+    }
     await sandbox.files.write("/home/user/agent.mjs", result.outputFiles[0].text);
     await sandbox.files.write("/home/user/runner.mjs", runnerCode);
     if (collectedExternals.size > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-neckbeard",
-  "version": "0.0.5",
+  "version": "1.0.0",
   "description": "Deploy AI agents to E2B sandboxes",
   "type": "module",
   "exports": {