MCPcopy Index your code
hub / github.com/21st-dev/21st-sdk

github.com/21st-dev/21st-sdk @main

Chat with this repo
repository ↗ · DeepWiki ↗ · + Follow
4,636 symbols 11,385 edges 1,296 files 158 documented · 3%
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

21st Agents SDK

Open-source SDK, runtime, and service code for building, deploying, and embedding 21st Agents.

Agent examples live in 21st-dev/21st-sdk-examples.

Architecture

Agent source
  -> @21st-sdk/cli bundles and deploys it
  -> apps/agents-web stores configs, API keys, docs, and dashboard state
  -> apps/relay authenticates requests, creates sandboxes, and streams runs
  -> packages/agent-runtime runs inside E2B/OpenSandbox
  -> apps/proxy validates sandbox JWTs and forwards model API calls
  -> @21st-sdk/react/nextjs/node/python embed or call the deployed agent

The runtime sandbox must be able to call both RELAY_URL and CLAUDE_PROXY_URL. If the sandbox runs remotely, localhost will not work for those values; expose local relay/proxy with ngrok, an AWS tunnel, or another public/internal tunnel.

Packages

Path Package Purpose
packages/agent @21st-sdk/agent Agent and tool definition helpers
packages/react @21st-sdk/react React chat UI components and tool renderers
packages/node @21st-sdk/node Server-side API client
packages/nextjs @21st-sdk/nextjs Next.js integration and token handler
packages/cli @21st-sdk/cli Agent deploy and management CLI
packages/python-sdk 21st-sdk Python API client
packages/agent-runtime @21st-sdk/agent-runtime Sandbox runtime for executing deployed agents
packages/sandbox-provider @repo/sandbox-provider Stream transformers and sandbox provider helpers
packages/api-key-security @repo/api-key-security Shared API key prefixing and hashing helpers

Apps

Path Purpose
apps/agents-web Agents dashboard, docs, deploy API, and web UI
apps/relay Relay service for chat, sandbox lifecycle, streams, and tokens
apps/proxy Model API proxy used by sandbox runtimes

Local Setup

Install dependencies:

pnpm install

For SDK-only work:

pnpm build
pnpm ts:check

Root build and ts:check are intentionally scoped to packages/*. Service apps have their own env and deployment requirements.

For a full local stack, create .env files for each service, then start them in separate terminals:

cp apps/agents-web/.env.example apps/agents-web/.env
cp apps/relay/.env.example apps/relay/.env
cp apps/proxy/.env.example apps/proxy/.env

# Optional local Redis, if you are not using a hosted REDIS_URL
docker run --rm -p 6379:6379 redis:7

# Terminal 1: model proxy
PORT=3003 pnpm --filter proxy dev

# Terminal 2: relay
PORT=3002 pnpm --filter relay dev

# Terminal 3: web app
pnpm --filter agents-web dev

Minimum env groups:

Service Key env vars
apps/agents-web DATABASE_URL, DIRECT_DATABASE_URL, auth provider env, NEXT_PUBLIC_APP_URL=http://localhost:3000, NEXT_PUBLIC_RELAY_URL=http://localhost:3002 or tunnel URL
apps/relay PORT=3002, DATABASE_URL, REDIS_URL, AN_JWT_SECRET, CLAUDE_PROXY_PRIVATE_JWT, CLAUDE_PROXY_URL, RELAY_URL, plus either E2B_API_KEY/RELAY_SANDBOX_TEMPLATE or OPENSANDBOX_*
apps/proxy PORT=3003, DATABASE_URL, JWT_PUBLIC_KEY, ANTHROPIC_API_KEY, optional OPENAI_API_KEY/OPENROUTER_API_KEY

When using remote E2B/OpenSandbox from a local machine, set:

RELAY_URL=https://<relay-tunnel>
CLAUDE_PROXY_URL=https://<proxy-tunnel>
NEXT_PUBLIC_RELAY_URL=https://<relay-tunnel>

For production-style self-hosting, start from apps/agents-web/infra.

Extension points exported contracts — how you extend this code

RedisSubscription (Interface)
(no doc) [4 implementers]
apps/agents-web/lib/redis.ts
SandboxBackend (Interface)
(no doc) [4 implementers]
apps/relay/src/sandbox-backends/types.ts
CachedToolState (Interface)
* Tool state cache for detecting AI SDK in-place mutations. * AI SDK mutates objects in-place during streaming, so we m
packages/react/src/utils/format-tool.ts
SpanJSON (Interface)
(no doc)
packages/agent-runtime/src/tracing.ts
SandboxProvider (Interface)
(no doc)
packages/sandbox-provider/src/sandbox-provider.ts
TokenHandlerOptions (Interface)
(no doc)
packages/nextjs/src/server.ts
ButtonProps (Interface)
(no doc)
packages/ui/src/button.tsx
AgentMcpServer (Interface)
(no doc)
packages/agent/src/types.ts

Core symbols most depended-on inside this repo

cn
called by 502
apps/agents-web/components/features/agents/ui/canvas/[id]/{components}/ui/utils.ts
get
called by 382
apps/agents-web/lib/redis.ts
set
called by 237
apps/agents-web/lib/redis.ts
cn
called by 198
apps/agents-web/lib/utils.ts
create
called by 110
apps/relay/src/sandbox-backends/types.ts
checkTeamAccess
called by 94
apps/agents-web/server/api/routers/teams/utils.ts
on
called by 81
apps/agents-web/lib/redis.ts
delete
called by 64
packages/node/src/client.ts

Shape

Function 3,706
Interface 538
Method 305
Class 85
Enum 1
Struct 1

Languages

TypeScript99%
Python1%
Go1%

Modules by API surface

apps/agents-web/components/features/agents/ui/canvas/[id]/{components}/ui/icons.tsx237 symbols
apps/relay/src/chat.ts55 symbols
apps/agents-web/lib/redis.ts53 symbols
packages/node/src/client.ts45 symbols
apps/agents-web/lib/agents-billing/ensure-team-billing.ts41 symbols
packages/python-sdk/src/twentyfirst_sdk/client.py39 symbols
apps/agents-web/app/api/style-profile/db-service.ts37 symbols
apps/agents-web/app/(alpha)/agents/studio/[projectId]/_components/workspace-client.tsx37 symbols
apps/agents-web/server/api/routers/semantic-chunk-search/services/ast-chunking.service.ts36 symbols
packages/node/src/types.ts34 symbols
apps/relay/src/sandbox-backends/opensandbox.ts33 symbols
packages/agent-runtime/src/index.ts30 symbols

For agents

$ claude mcp add 21st-sdk \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact