DX-2548: add configurable box sizes (small, medium, large)

[CahidArda]

New Box API Endpoints — SDK Support

Progress

• Box Sizes — size option on Box.create() and Box.fromSnapshot()
• Delete Multiple Boxes — Box.delete() and Box.deleteAll() static methods + BoxConnectionOptions refactor
• Agent Options — Type-safe agentOptions on RunOptions / StreamOptions with Box<TProvider> generic
• Skills API — box.skills.add(), box.skills.remove(), box.skills.list() + enabled_skills on BoxData
• Multi-Modal Prompt Files — files field on run/stream with multipart form data support
• Check if ephemeral box allows size option and update accordingly
• Make agent options camel case
• Get Box by ID or Name — skipped (already works transparently)
• CLAUDE.md & Skills Support — skipped (server-side behavior, no SDK change needed)
• fromSnapshot new fields — network_policy and attach_headers already sent; size covered by Box Sizes

---

Box Sizes

Choose CPU and memory allocation at creation time. Defaults to "small".

const box = await Box.create({
  size: "large", // 8 cores, 16 GB
  agent: { provider: Agent.ClaudeCode, model: ClaudeCode.Sonnet_4_6 },
});

console.log(box.size); // "large"

Also works with snapshots:

const box = await Box.fromSnapshot("snap_abc123", { size: "medium" });

Implementation details

• New BoxSize type ("small" | "medium" | "large") added to BoxConfig, BoxData, and exported from the package
• box.size is a readonly property on Box instances, defaulting to "small" when the API response omits it
• Box.create() and Box.fromSnapshot() send size in the request body when provided
• New "Box Sizes" section added to README with pricing table and examples
• Unit tests on create/fromSnapshot for sending and omitting size
• Integration test creates boxes with all three sizes and verifies via Box.get()

Delete Multiple Boxes

Delete specific boxes by ID, or wipe all at once.

// Delete one
await Box.delete({ boxIds: "box-abc", apiKey: "..." });

// Delete several
await Box.delete({ boxIds: ["box-1", "box-2", "box-3"], apiKey: "..." });

// Delete all
await Box.deleteAll({ apiKey: "..." });

Both methods are also available on EphemeralBox:

await EphemeralBox.delete({ boxIds: "box-abc", apiKey: "..." });
await EphemeralBox.deleteAll({ apiKey: "..." });

Implementation details

• New BoxConnectionOptions base interface (apiKey, baseUrl) — BoxConfig, EphemeralBoxConfig, ListOptions, and BoxGetOptions now extend it instead of redeclaring those fields
• Box.delete() sends DELETE /v2/box with { ids: [...] } JSON body
• Box.deleteAll() sends DELETE /v2/box without a body
• EphemeralBox.delete and EphemeralBox.deleteAll delegate to the Box static methods
• Unit tests for single/multiple ID deletion, deleteAll, missing apiKey, env var fallback, and API errors on both Box and EphemeralBox
• Integration test creates ephemeral boxes and verifies deletion via Box.list()

Agent Options

Pass SDK-specific options to the underlying agent. The options are type-checked based on the provider.

// Claude Code — typed options
const box = await Box.create<Agent.ClaudeCode>({
  agent: { provider: Agent.ClaudeCode, model: ClaudeCode.Sonnet_4_6 },
});

const run = await box.agent.run({
  prompt: "Refactor auth.ts",
  agentOptions: {
    maxTurns: 5,
    effort: "max",
    thinking: { type: "enabled", budgetTokens: 16000 },
  },
});

// Codex — different options surface
const box = await Box.create<Agent.Codex>({
  agent: { provider: Agent.Codex, model: OpenAICodex.GPT_5_3_Codex },
});

await box.agent.run({
  prompt: "Fix the tests",
  agentOptions: {
    model_reasoning_effort: "high",
    personality: "pragmatic",
    web_search: true,
  },
});

// OpenCode
const box = await Box.create<Agent.OpenCode>({
  agent: { provider: Agent.OpenCode, model: OpenCodeModel.Claude_Sonnet_4_6 },
});

await box.agent.stream({
  prompt: "Add logging",
  agentOptions: {
    reasoningEffort: "high",
    textVerbosity: "low",
  },
});

Also works with webhooks:

await box.agent.run({
  prompt: "Deploy",
  agentOptions: { maxTurns: 3 },
  webhook: { url: "https://example.com/hook" },
});

Implementation details

• ClaudeCodeAgentOptions — maxTurns, maxBudgetUsd, effort, thinking, disallowedTools, agents, promptSuggestions, fallbackModel, systemPrompt
• CodexAgentOptions — model_reasoning_effort, model_reasoning_summary, personality, web_search
• OpenCodeAgentOptions — reasoningEffort, textVerbosity, reasoningSummary, thinking
• AgentOptions<TProvider> conditional type resolves to the correct interface based on the provider
• Box<TProvider> — the Box class is now generic. Box.create<TProvider>(), Box.get<TProvider>(), and Box.fromSnapshot<TProvider>() propagate the provider so agentOptions in run() and stream() is type-checked
• agentOptions is serialized as agent_options in the JSON request body for all run paths (streaming, non-streaming, webhook)
• Unit tests per provider (ClaudeCode, Codex, OpenCode) for both run and stream
• Integration test with Claude Code agent options

Skills API

Add, remove, and list platform skills from the Context7 registry on a box.

// Add a skill
await box.skills.add("vercel/next.js/update-docs");

// List enabled skills
const skills = await box.skills.list();

// Remove a skill
await box.skills.remove("vercel/next.js/update-docs");

Planned implementation

• enabled_skills?: string[] on BoxData
• box.skills.add(skillId) — POST /v2/box/{id}/config/skills with { skill_id }
• box.skills.remove(skillId) — DELETE /v2/box/{id}/config/skills/{owner}/{repo}/{skill}
• box.skills.list() — returns enabled_skills from box data

Multi-Modal Prompt Files

Attach files to prompts. Two formats supported:

// Base64 (sent as JSON)
await box.agent.run({
  prompt: "What's in this image?",
  files: [
    { data: "iVBORw0KGgo...", mediaType: "image/png", filename: "screenshot.png" },
  ],
});

// Local file paths (sent as multipart form data)
await box.agent.run({
  prompt: "Analyze this CSV",
  files: ["./data/report.csv", "./data/summary.csv"],
});

Both formats work with box.agent.run() and box.agent.stream():

const run = await box.agent.stream({
  prompt: "What color is this?",
  files: [{ data: tinyPng, mediaType: "image/png" }],
});

for await (const chunk of run) {
  if (chunk.type === "text-delta") process.stdout.write(chunk.text);
}

Testing with curl

# Multipart (file path)
curl -X POST "https://us-east-1.box.upstash.com/v2/box/BOX_ID/run" \
  -H "X-Box-Api-Key: API_KEY" \
  -F 'prompt=How many rows in this CSV?' \
  -F 'files=@./data/report.csv'

# JSON (base64)
curl -X POST "https://us-east-1.box.upstash.com/v2/box/BOX_ID/run" \
  -H "X-Box-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Describe this image","files":[{"data":"iVBORw0KGgo...","media_type":"image/png"}]}'

Implementation details

• PromptFiles type: string[] (file paths → multipart) or { data, mediaType, filename? }[] (base64 → JSON)
• files?: PromptFiles added to both RunOptions and StreamOptions
• buildRunRequest() helper detects format: file paths build a FormData with binary parts; base64 objects are serialized as files array in JSON with media_type wire format
• buildMultipartBody() reads files from disk, appends all options as form fields (objects serialized as JSON strings)
• Unit tests for both formats across run, stream, and webhook paths
• Integration tests with base64 images and local CSV file uploads

[linear]

DX-2548 box - update sdk with box size, skills namespace, static delete box methods