Claude Agent SDK App
AdvancedAi AgentsAgents on the harness behind Claude Code: a TypeScript service with built-in file, shell, and web tools, running Claude in containers you control.
Published 12 October 2026
About Claude Agent SDK App
The agent is Claude Code's harness, used as a library. The Claude Agent SDK gives a TypeScript service the same loop, built-in tools for reading and editing files, running shell commands, searching, and fetching from the web, the context compaction, subagents, hooks, permission modes, and MCP connections that Claude Code runs on. Building an agent is mostly writing its instructions, its permissions, and its custom tools, not the loop. The model is fixed: the SDK works with Claude only, through an Anthropic API key or the major clouds' Claude endpoints, which is the trade against a framework that lets you swap model vendors.
Each session is a Claude Code subprocess with its own shell and working directory, which the SDK spawns and talks to over stdio. So the service runs in a container, not a serverless function: Node.js 18 or later, the SDK with its bundled binary, and a Docker image. Anthropic's starting point is 1 GB of memory, 5 GB of disk, and one CPU per concurrent agent, and memory grows with session length. Where that container lives is the stack's main choice: a long-running host that keeps many sessions warm, or a sandbox platform that starts a fresh, isolated machine for each task and discards it afterwards.
Sessions live on local disk by default, so transcripts, memory files, and whatever the agent writes in its working directory disappear when the container restarts. Agents that users come back to need a session store, which mirrors transcripts to an object store, a key-value store, or a database, and the working directory needs a volume or a sync of its own. Because the agent runs shell commands, Anthropic's guidance is to give each tenant its own working directory and configuration directory, send outbound traffic through a proxy with an allowlist, keep tool credentials out of the container, and authenticate users at a gateway in front of the service.
Token spend dominates the bill. Anthropic puts a small container at about $0.05 an hour, while one long session can spend dollars on Claude, so a cap on turns, the model chosen for each subagent, and the SDK's cost tracking matter more than the host. Tracing through OpenTelemetry, a session store, and CI are optional additions.
Key Features
- ✓The Claude Agent SDK in TypeScript: Claude Code's agent loop, built-in file, shell, search, and web tools, and context compaction
- ✓Subagents, lifecycle hooks, permission modes, and skills to shape what the agent may do
- ✓Custom tools as in-process MCP servers, plus connections to external MCP servers
- ✓Claude as the model, through an Anthropic API key or the major clouds' Claude endpoints
- ✓Runs in a container: a long-running host or a per-task sandbox, Railway by default
- ✓Optional session stores that keep transcripts in S3, Redis, or PostgreSQL
When to Use Claude Agent SDK App
- →A coding or data agent that edits files and runs commands in its own workspace
- →Back-office automation: an email, ticket, or document agent driven by a queue or a schedule
- →A research agent that searches the web, reads sources, and writes a report
- →Per-customer agents in a SaaS product, each in an isolated sandbox
- →Wrapping internal systems as MCP servers that an agent can call
Pros
- Starts from a harness proven on real coding work, with file and shell tools ready to use
- Subagents, hooks, permissions, and resumable sessions are built in, not assembled
- Per-task sandboxes give strong isolation for agents that run the code they write
- Hosting cost is small next to model usage, so the host can be chosen for fit, not price
Cons
- Claude only: switching model vendors means rewriting the agent
- Each session is a subprocess, so it needs containers, not serverless functions
- Sessions and files vanish on restart unless a store and a volume are added
- The TypeScript package is under Anthropic's Commercial Terms, not an open-source licence
Hosting Options for Claude Agent SDK App
The default: a container platform that keeps the agent service running, so long-running sessions stay warm and take new turns over HTTP or WebSocket. Attach a volume for working directories and transcripts, or they go with each redeploy. Memory is billed at about $10 per GB a month on top of the $5 Hobby plan, so Anthropic's starting point of 1 GB per concurrent agent comes to roughly $10 a month for each agent running at the same time. TLS and a public domain come with the platform.
Machines that start on a request and stop when idle, billed per second, which suits the hybrid pattern: a returning user's session hydrates from a session store and the machine shuts down between visits. Volumes keep working directories on a machine, and regions put agents near their users. A 1 GB machine left running costs under $10 a month. The service ships as a Docker image, so expect a little more setup than a Git-push platform.
A root VPS for running many agents in one pool: a shared-vCPU server with 8 GB at about €35 a month holds roughly six concurrent agents at Anthropic's 1 GB starting point, and a 4 GB one at about €19 holds two or three. It is the cheapest per agent under steady load, but isolation between tenants, restarts, TLS, and scaling are yours to build with Docker and a proxy.
These are highlighted picks. To see all the tools, check the Hosting & Cloud category.
Code Sandbox Options for Claude Agent SDK App
The platform in Anthropic's own hosting cookbook: each task gets a fresh sandbox that runs the agent and is destroyed when it finishes, the ephemeral pattern. Sandboxes bill per second, about $0.17 an hour for one physical core and 1 GiB, and the free Starter plan includes $30 of credits a month. Volumes keep files between runs. It fits one-off tasks such as fixing a bug or processing a document. The service that starts each sandbox is only a few API calls, so it can run on any host, a serverless function included.
Firecracker microVM sandboxes started from a TypeScript SDK in a fraction of a second, with the agent service running inside like any Node.js process. Each user or task gets its own virtual machine, the strongest separation for agents that run shell commands. The free Hobby plan's one-time credits cap a sandbox at one hour, so long-running agents need Pro at $150 a month, which allows 24 hours. Usage is billed per second.
Sandboxes the vendor says start in under 90 milliseconds and that can run with no time limit once auto-stop is switched off, driven from a TypeScript SDK with file, Git, and process APIs. That suits an agent that keeps the same environment across many sessions, such as a per-user workspace. Billing is per second while a sandbox runs, a stopped one pays only for its disk, and new accounts get starter credits.
These are highlighted picks. To see all the tools, check the Agent Sandboxes & Code Execution category.
Claude Agent SDK App Add-ons
Each addition below extends this stack with a capability the base stack works fine without. None are required: include the ones your product actually needs when building this stack, and skip the rest.
Database Add-ons
Add a database when the app needs to persist data between sessions: user records, application state, or anything that should survive a restart.
Anthropic's Postgres reference adapter stores each transcript entry as a JSON row ordered on insert; copy it into the project as the session store, and the same database can hold your users and job records. Pick it when sessions are part of your product's data and need queries, retention rules, and backups you already run.
The key-value reference adapter keeps one list per transcript plus a sorted index of sessions, so appends are fast and resuming is cheap, which suits the long-running pattern with many short turns. Turn on Redis persistence, or treat transcripts as disposable, since an in-memory store loses them on restart.
These are highlighted picks. To see all the tools, check the Databases category.
LLM Observability Add-ons
Add LLM observability when you want to see every model call, tool call, and token cost inside a run, so a wrong answer can be traced to the step that caused it.
Langfuse documents a Claude Agent SDK integration for TypeScript and Python that sends OpenTelemetry spans for each agent run and tool call, with token totals and cost. With the current instrumentation a trace shows the run and its tools rather than every model call. Open source, self-hostable, or on the cloud's free Hobby plan.
LangSmith instruments the SDK through its own Claude Agent SDK support, so runs, tool calls, and subagents arrive as traces beside any LangChain work. It is hosted and closed source, with self-hosting on Enterprise only; the free Developer plan covers one seat and 5,000 traces a month.
Object Storage Add-ons
Add object storage when your app accepts file uploads or produces files, such as avatars, documents, images, and exports, and those files should live outside your database and server disk.
The object-store reference adapter writes one part file per batch and reads them back in order on resume: the cheapest durable home for transcripts, with lifecycle rules for retention, which the SDK leaves to you. A bucket also suits the working-directory files that session stores don't cover, synced when a task ends.
These are highlighted picks. To see all the tools, check the Object Storage category.
CI/CD Add-ons
Add CI/CD when you want a dedicated pipeline for running tests, linting, or multi-stage builds before a deploy goes out. Many hosting platforms already redeploy automatically on every push on their own — a CI/CD tool adds the most value on top of that by gating the deploy on a passing test suite, and matters even more when the hosting choice does not auto-deploy at all, such as a self-hosted server.
Builds and pushes the agent's Docker image, runs type checks and tests, and adds the step that matters for agents: replay saved tasks against a changed prompt, permission set, or model, and fail the build when the results get worse. Pin the SDK version, since it also pins the bundled Claude Code binary.
These are highlighted picks. To see all the tools, check the CI/CD Pipelines category.
Frequently Asked Questions about Claude Agent SDK App
Should I use the Agent SDK, the Claude API's tool runner, or Managed Agents?
All three run an agent on Claude; they differ in how much comes built in and who runs it. The tool runner in Anthropic's client SDK is the thinnest: it loops over tools you define and nothing else, with no file or shell tools and no sessions, and it runs in any process, including serverless functions. The Agent SDK, this stack, adds Claude Code's built-in tools, subagents, hooks, permissions, and sessions, at the price of running a subprocess in a container you operate. Managed Agents moves the loop and the sandbox to Anthropic, configured through the API, so there is no container to run, but the agent runs on Anthropic's platform under its controls. Pick the SDK when the agent needs a real shell and files and you want to own where it runs.
Should the agent run in a long-running container or a fresh sandbox per task?
It follows the work. One-off tasks, such as fixing a bug or extracting an invoice, suit a fresh sandbox that is destroyed afterwards, which gives clean isolation and no state to clean up. An agent serving continuous traffic, such as a chat bot or an email triager, suits a long-running container holding many sessions warm. Sessions that pause for hours, such as research that resumes later, suit the hybrid: a container that shuts down when idle and reloads the transcript from a session store when the user returns, which makes the store mandatory. The agent runs on one of the two kinds of platform, a container host or a sandbox platform, and they map to these patterns: Railway and Hetzner for long-running pools, Modal and E2B for per-task sandboxes, Fly.io and Daytona for the hybrid.
What drives the model bill, and can a Claude subscription pay for it?
Tokens, not hosting. Every turn resends the instructions, tool definitions, and conversation so far, and file and shell tools pull long outputs into the context, so a long session costs more with each step. Cap turns per session, give subagents a cheaper model for simple steps, keep tool output short, and track cost per session with the SDK's accounting; the Pricing section has the per-token rates. A Claude Pro or Max subscription can't pay for a product built on the SDK: Anthropic's docs say products may not offer claude.ai login or its rate limits unless approved, so billing goes through an API key, or through Bedrock, Google Cloud, or Foundry on your cloud account.
How is this different from the TypeScript AI Agent stack?
TypeScript AI Agent builds the agent with a framework, the Vercel AI SDK by default, inside a Next.js app that also renders the chat, and it can switch between Claude, OpenAI, and Gemini. It runs well on serverless hosting, and you write each tool yourself. This stack starts from Claude Code's harness instead: file editing, shell commands, web search, subagents, and sessions come built in, but it is Claude only and each session needs a container. Pick TypeScript AI Agent for a chat assistant inside a web product, and this stack for an agent that works on files and runs commands, or when you want a harness proven on coding work rather than one you assemble.
Can I put a web interface in front of the agent?
Yes, and the agent service stays separate from it. The container exposes an HTTP or WebSocket endpoint, keeps each user's session mapped to its subprocess, and streams messages back as the agent works. A Next.js app, such as the interface in the TypeScript AI Agent stack, or any other web frontend calls that endpoint and renders the stream, including tool calls. Anthropic's guidance puts user authentication at a gateway in front of the agent container, so the frontend and the gateway handle sign-in and the agent only sees requests that are already authorised. For agents with no interface, a queue or a scheduler can call the same endpoint.
Can I write the agent in Python instead of TypeScript?
Yes. The Python package has the same loop, tools, hooks, subagents, MCP support, and session stores, needs Python 3.10 or later, and bundles the same binary; it is also the MIT-licensed one of the two. The differences are in the API surface: Python holds a session open with a client object where TypeScript streams input into a running query, and a few helpers, such as pre-warming subprocesses, exist only in TypeScript. Everything else in this stack carries over: the hosts, the session stores, and the tracing. Choose the language your team and your tools already use.
Stacks Related to Claude Agent SDK App
Vue + Node.js + PostgreSQL
ProjectVue 3 SPA with Node.js/Express backend and PostgreSQL: a full JavaScript stack with a relational database.
Express + MongoDB
ProjectNode.js REST API with MongoDB for flexible schema and fast JavaScript development.
Svelte + FastAPI
ProjectSvelte SPA frontend with FastAPI backend: minimal JavaScript output meets Python API performance.
Spring Boot + Angular
ProjectEnterprise full-stack TypeScript-meets-Java: an Angular frontend backed by a Spring Boot REST API.
Scores
Popularity4/5
Built on Claude Code, one of the most widely used coding agents, and the SDK Anthropic points developers to for their own agents, with a growing number of guides and templates. Known among teams building agents more than among developers at large.
Learning Curve4/5
A first agent is a few lines around one query call, but production asks for more: a subprocess per session in containers, session stores, per-tenant isolation, an egress proxy, permission modes that decide what the agent may run, and cost control over long sessions.
Flexibility3/5
Tools, MCP servers, hooks, subagents, and permissions make the agent itself very configurable, and it runs on any container host or sandbox platform. The model is fixed to Claude, though, and the harness's loop is Claude Code's, not one you design.
Performance4/5
The harness is the one Claude Code runs on, with context compaction and parallel subagents for long tasks. Each session is a full subprocess whose memory grows with its length, so concurrency per host is bounded and long sessions need recycling.
Portability2/5
The containers, session stores, and hosts are ordinary and portable, but the agent is tied to Claude and to Claude Code's harness, and the TypeScript package is under Anthropic's Commercial Terms. Moving to another vendor means rebuilding the agent on a different framework.
Tools in the Claude Agent SDK App Stack
Backend Frameworks
Programming Languages
DevOps & CI/CD
LLM
Agentic AI
Add-ons (optional — add any, or none)
Database
LLM Observability
Object Storage
CI/CD
Claude Agent SDK App Pricing
The SDK is free to install, so the costs are a container and the tokens, and tokens dominate: Anthropic puts a small container at about $0.05 an hour, while one long agent session can spend dollars on Claude. A container host costs about $10 a month for each agent running at the same time, and sandbox platforms bill by the second with free credits to start. Model usage is billed per token through your API key or cloud account.
Anthropic's starting point is 1 GB of memory and one CPU per concurrent agent: about $10 a month per agent on Railway, under $10 for a 1 GB Fly.io machine, about €19 to €35 for a 4 to 8 GB Hetzner server holding several agents, or per-second sandboxes on Modal (about $0.17 an hour, with $30 of monthly credits), E2B, or Daytona.
Sonnet costs $2 per million input tokens and $10 per million output, Haiku $1 and $5, and Opus $4 and $20. Each turn resends the conversation and tool results, so long sessions cost more per step; caps on turns and a cheaper model for subagents keep it in check.
Free to install. The Python package is MIT-licensed; the TypeScript package and the bundled Claude Code binary are used under Anthropic's Commercial Terms.