OSS Release

Author: Danverr

.gitignore

@@ -1,11 +1,26 @@
 node_modules/
 dist/
+build/
+.next/
+out/
 .turbo/
+.vercel/
+.clerk/
 .env
 .env.*
+!.env.example
+!*.env.example
 .DS_Store
 *.tgz
 CLAUDE.md
+terraform.tfstate
+terraform.tfstate.*
+terraform.tfvars
+*.auto.tfvars
+*.auto.tfvars.json
+tfplan*
+apps/agents-web/prisma/client/
+apps/agents-web/public/an-docs-markdown/
 __pycache__/
 *.py[cod]
 .venv/

README.md

@@ -1,96 +1,98 @@
-# 21st SDK — Internal Dev Guide
+# 21st Agents SDK
 
-This directory contains the 21st SDK packages. Source of truth lives here in the monorepo. The public open-source repo is at [github.com/21st-dev/21st-sdk](https://github.com/21st-dev/21st-sdk).
+Open-source SDK, runtime, and service code for building, deploying, and embedding 21st Agents.
 
-## Packages
-
-| Directory | Package | What it does |
-|---|---|---|
-| `agent/` | `@21st-sdk/agent` | Agent + tool definition (types only) |
-| `react/` | `@21st-sdk/react` | React chat UI components |
-| `node/` | `@21st-sdk/node` | Node.js API client |
-| `nextjs/` | `@21st-sdk/nextjs` | Next.js integration (server + client) |
-| `cli/` | `@21st-sdk/cli` | `an login` + `an deploy` CLI |
-| `python-sdk/` | `21st-sdk` (PyPI) | Python API client |
-| `docs/` | — | Documentation (bundled into each package on publish) |
+## Architecture
 
-> **Note:** `agent-runtime` used to be here but was moved to `packages/agent-runtime/` — it's private and should never be in the public repo.
-
-## Day-to-day development
+```text
+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
+```
 
-Just work in the monorepo as normal. Edit files, run builds, test locally.
+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.
 
-```bash
-# Build all SDK packages
-pnpm --filter "@21st-sdk/*" build
+## Packages
 
-# Build a specific package
-pnpm --filter @21st-sdk/react build
-```
+| 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 |
 
-## Publishing to the open-source repo
+## Apps
 
-When you're ready to push changes to the public [github.com/21st-dev/21st-sdk](https://github.com/21st-dev/21st-sdk):
+| 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 |
 
-### Prerequisites (one-time setup)
+## Local Setup
 
-Clone the public repo as a sibling of the monorepo:
+Install dependencies:
 
 ```bash
-cd /Users/sergeybunas/Develop/21/
-git clone git@github.com:21st-dev/21st-sdk.git
+pnpm install
 ```
 
-So your directory structure looks like:
+For SDK-only work:
 
-```
-Develop/21/
-├── 21st/       ← monorepo (this repo)
-└── 21st-sdk/     ← public repo
+```bash
+pnpm build
+pnpm ts:check
 ```
 
-### Releasing
+Root `build` and `ts:check` are intentionally scoped to `packages/*`. Service
+apps have their own env and deployment requirements.
 
-From the monorepo root:
+For a full local stack, create `.env` files for each service, then start them in
+separate terminals:
 
 ```bash
-# Option 1: Auto-generate commit message from recent monorepo commits
-./scripts/release-sdk.sh
+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
 
-# Option 2: Custom commit message
-./scripts/release-sdk.sh -m "feat: add theme customization API to @21st-sdk/react"
+# Optional local Redis, if you are not using a hosted REDIS_URL
+docker run --rm -p 6379:6379 redis:7
 
-# Option 3: Tagged release (creates a git tag)
-./scripts/release-sdk.sh -t v0.2.0 -m "v0.2.0 — streaming improvements and new tool renderers"
-```
+# Terminal 1: model proxy
+PORT=3003 pnpm --filter proxy dev
 
-Then push:
+# Terminal 2: relay
+PORT=3002 pnpm --filter relay dev
 
-```bash
-cd ../21st-sdk && git push        # regular release
-cd ../21st-sdk && git push --tags # if you created a tag
+# Terminal 3: web app
+pnpm --filter agents-web dev
 ```
 
-### What the script does
-
-1. Copies `agent/`, `react/`, `node/`, `nextjs/`, `cli/`, `python-sdk/`, `docs/` to the public repo
-2. Excludes `node_modules/`, `dist/`, `.turbo/`, `CLAUDE.md` (private dev notes)
-3. If no `-m` flag, pulls recent commit messages from the monorepo that touched `packages/an-sdk/` and uses them as the commit message
-4. Creates a commit in the public repo (skips if nothing changed)
-5. Optionally tags the commit with `-t`
-
-### What NOT to do
-
-- Don't develop directly in the public repo — always work in the monorepo
-- Don't manually copy files — always use the release script
-- Don't include `agent-runtime` — the script only copies the 7 listed packages
+Minimum env groups:
 
-## Publishing to npm
+| 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` |
 
-npm publishing still happens from the monorepo, not the public repo:
+When using remote E2B/OpenSandbox from a local machine, set:
 
 ```bash
-pnpm --filter @21st-sdk/agent build && npm publish --access public
+RELAY_URL=https://<relay-tunnel>
+CLAUDE_PROXY_URL=https://<proxy-tunnel>
+NEXT_PUBLIC_RELAY_URL=https://<relay-tunnel>
 ```
 
-See the [NPM Publishing notes](../../.claude/projects/-Users-sergeybunas-Develop-21-21st/memory/MEMORY.md) for auth details.
+For production-style self-hosting, start from `apps/agents-web/infra`.

apps/agents-web/.env.example

@@ -0,0 +1,67 @@
+# App URLs
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NEXT_PUBLIC_AGENTS_WEB_URL=http://localhost:3000
+NEXT_PUBLIC_RELAY_URL=http://localhost:3002
+NEXT_PUBLIC_IS_STANDALONE_APP=false
+NEXT_PUBLIC_AGENTS_AUTH_MODE=clerk
+
+# Database
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/21st_agents?sslmode=disable
+DIRECT_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/21st_agents?sslmode=disable
+
+# Auth: Clerk is the default non-standalone mode.
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_replace_me
+CLERK_SECRET_KEY=sk_test_replace_me
+CLERK_WEBHOOK_SECRET=whsec_replace_me
+
+# Supabase-compatible APIs used by search/profile routes.
+NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
+NEXT_PUBLIC_SUPABASE_KEY=replace_me
+SUPABASE_SERVICE_ROLE_KEY=replace_me
+
+# Internal service auth
+INTERNAL_API_SECRET=replace_me
+API_KEY_21ST=21st_sk_replace_me
+AN_API_KEY=21st_sk_replace_me
+BUILDER_WIZARD_API_KEY=21st_sk_replace_me
+BUILDER_WIZARD_JWT_SECRET=replace_me
+CLAUDE_PROXY_PRIVATE_JWT="-----BEGIN PRIVATE KEY-----\nreplace_me\n-----END PRIVATE KEY-----"
+
+# Sandbox/deploy defaults
+SANDBOX_PROVIDER=e2b
+RELAY_SANDBOX_TEMPLATE=replace_me
+OPENSANDBOX_RUNTIME_IMAGE=
+
+# Optional local services and integrations
+REDIS_URL=redis://localhost:6379
+OPENAI_API_KEY=
+OPENROUTER_API_KEY=
+RESEND_API_KEY=
+STRIPE_SECRET_KEY_V1=
+STRIPE_SECRET_KEY_V2=
+STRIPE_WEBHOOK_SECRET_V1=
+STRIPE_WEBHOOK_SECRET_V2=
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY_V2=
+
+# Optional storage/CDN
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+NEXT_PUBLIC_R2_ENDPOINT=
+NEXT_PUBLIC_CDN_URL=
+
+# Optional analytics. Keep disabled locally unless you intentionally configure a project.
+NEXT_PUBLIC_FORCE_ANALYTICS=false
+NEXT_PUBLIC_POSTHOG_KEY=
+NEXT_PUBLIC_POSTHOG_HOST=
+NEXT_PUBLIC_POSTHOG_AGENTS21ST_KEY=
+NEXT_PUBLIC_POSTHOG_AGENTS21ST_HOST=
+
+# Standalone / Better Auth alternative. Uncomment instead of Clerk when self-hosting that mode.
+# NEXT_PUBLIC_IS_STANDALONE_APP=true
+# NEXT_PUBLIC_AGENTS_AUTH_MODE=better-auth
+# BETTER_AUTH_URL=http://localhost:3000
+# NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3000
+# BETTER_AUTH_SECRET=replace_me
+# BETTER_AUTH_OKTA_SAML_ISSUER=
+# BETTER_AUTH_OKTA_SAML_ENTRY_POINT=
+# BETTER_AUTH_OKTA_SAML_CERT=

apps/agents-web/.eslintrc.js

@@ -0,0 +1,45 @@
+/** @type {import("eslint").Linter.Config} */
+module.exports = {
+  root: true,
+  extends: ["@repo/eslint-config/next.js"],
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    project: true,
+  },
+  rules: {
+    "@next/next/no-img-element": "off",
+  },
+  overrides: [
+    {
+      files: ["tailwind.config.js"],
+      parser: "espree",
+      parserOptions: {
+        ecmaVersion: 2020,
+      },
+    },
+    // Warn about using Clerk's useAuth directly in agents/canvas sections
+    // Desktop auth requires useCombinedAuth() instead
+    {
+      files: [
+        "app/(alpha)/agents/**/*.{ts,tsx}",
+        "app/agents/**/*.{ts,tsx}",
+        "app/(alpha)/canvas/**/*.{ts,tsx}",
+      ],
+      rules: {
+        "no-restricted-imports": [
+          "warn",
+          {
+            paths: [
+              {
+                name: "@clerk/nextjs",
+                importNames: ["useAuth"],
+                message:
+                  "Use useCombinedAuth() from '@/lib/hooks/use-combined-auth' instead for desktop auth support.",
+              },
+            ],
+          },
+        ],
+      },
+    },
+  ],
+}

apps/agents-web/.gitignore

@@ -0,0 +1,47 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# env files (can opt-in for commiting if needed)
+.env*
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# css
+css/*
+.env*.local
+
+/prisma/client
+claude-code-output.log
+
+# Per-developer paste workflow for scripts/generate-mcp-registry.ts
+/scripts/raw_html.local.html