diff --git a/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md b/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md index ff989b3..eef5d53 100644 --- a/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md +++ b/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md @@ -23,6 +23,10 @@ created: 2026-04-17 - **Local path:** `/Volumes/SSD/Projects/Oliver/Barclays-banner-builder` ## Sessions +### 2026-04-17 – Create an idempotent deployment script for +**Asked:** Create an idempotent deployment script for Ubuntu with Docker, database migrations, and Apache reverse proxy configuration. +**Done:** Diagnosed and fixed Apache vhost Include directive ordering issue by reordering configuration includes on the production server. + ### 2026-04-17 – Create deployment script and app concept **Asked:** Create deployment script and app concept for Docker-based Ubuntu server with Apache reverse proxy, avoiding WebSockets. **Done:** Fixed Apache configuration routing issue by reordering Include directives so the app's config loads before hp-prod-tracker's catch-all rule. @@ -131,6 +135,7 @@ created: 2026-04-17 ## Change Log | Date | Requested | Changed | Files | |------|-----------|---------|-------| +| 2026-04-17 | Deployment script & Apache config | Docker build with cache management, database initialization, Alembic migrations, frontend cleanup, vhost Include directive reordering | deploy.sh, /etc/apache2/sites-available/optical-dev.oliver.solutions.conf | | 2026-04-17 | Deployment setup | Apache conf Include order, deploy.sh idempotent script | deploy.sh, /etc/apache2/sites-available/optical-dev.oliver.solutions.conf | | 2026-04-17 | Deployment setup | deploy.sh creation, Apache VirtualHost reordering, Docker build cache management | deploy.sh, /etc/apache2/sites-available/optical-dev.oliver.solutions.conf | | 2026-04-17 | Deployment script & Apache config | Docker build caching, idempotent database init, Alembic migrations, Apache ProxyPass setup | deploy.sh, optical-dev.oliver.solutions.conf | diff --git a/99 Daily/2026-04-17.md b/99 Daily/2026-04-17.md index 3b75e80..7ee032a 100644 --- a/99 Daily/2026-04-17.md +++ b/99 Daily/2026-04-17.md @@ -164,3 +164,9 @@ tags: [daily] - 12:50 | `memory-compiler` - **Asked:** Compile a new article about user input approvals into the agent-sdk wiki section. - **Done:** Created structured wiki article documenting canUseTool and AskUserQuestion with response strategies and workarounds. +- 12:50 (<1min) | `Barclays-banner-builder` + - **Asked:** Create an idempotent deployment script for Ubuntu with Docker, database migrations, and Apache reverse proxy configuration. + - **Done:** Diagnosed and fixed Apache vhost Include directive ordering issue by reordering configuration includes on the production server. +- 12:51 | `memory-compiler` + - **Asked:** Compile a new article about Agent SDK hosting into the wiki knowledge base. + - **Done:** Filed structured article as `agent-sdk/hosting-production.md` with deployment patterns, system requirements, and provider options. diff --git a/raw/Hosting the Agent SDK.md b/raw/_processed/Hosting the Agent SDK.md similarity index 100% rename from raw/Hosting the Agent SDK.md rename to raw/_processed/Hosting the Agent SDK.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index c754b4d..4bd90e9 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -30,7 +30,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/web-agency/_index\|web-agency/]] | AI-assisted website building & selling: Claude Code, Nanobanana 2, Kling, LaunchPath MCP | 1 | | [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby | 9 | -| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 11 | +| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 12 | | [[wiki/llm-models/_index\|llm-models/]] | OpenAI model catalog — GPT-5.x, o-series reasoning, audio/realtime, embeddings, moderation | 1 | | [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, error recovery | 7 | diff --git a/wiki/agent-sdk/_index.md b/wiki/agent-sdk/_index.md index 2d03f0c..dce71cd 100644 --- a/wiki/agent-sdk/_index.md +++ b/wiki/agent-sdk/_index.md @@ -25,3 +25,4 @@ Build production AI agents using the same tools, agent loop, and context managem | [[wiki/agent-sdk/structured-outputs\|structured-outputs]] | Return validated JSON from agent workflows using JSON Schema, Zod, or Pydantic; error subtypes, tips | raw/Get structured output from agents.md | 2026-04-17 | | [[wiki/agent-sdk/custom-tools\|custom-tools]] | Define custom tools with @tool/@tool(), in-process MCP server, error handling, images, resources, annotations | raw/Give Claude custom tools.md | 2026-04-17 | | [[wiki/agent-sdk/user-input-approvals\|user-input-approvals]] | canUseTool callback: tool approvals, AskUserQuestion clarifying questions, allow/deny/modify, Python streaming workaround | raw/Handle approvals and user input.md | 2026-04-17 | +| [[wiki/agent-sdk/hosting-production\|hosting-production]] | Production hosting: container requirements, 4 deployment patterns (ephemeral/long-running/hybrid/multi-agent), sandbox providers, ops notes | raw/Hosting the Agent SDK.md | 2026-04-17 | diff --git a/wiki/agent-sdk/hosting-production.md b/wiki/agent-sdk/hosting-production.md new file mode 100644 index 0000000..0a2c785 --- /dev/null +++ b/wiki/agent-sdk/hosting-production.md @@ -0,0 +1,95 @@ +--- +title: "Hosting the Agent SDK in Production" +aliases: [agent-sdk-hosting, sdk-deployment, sdk-production] +tags: [agent-sdk, hosting, deployment, containers, production] +sources: [raw/Hosting the Agent SDK.md] +created: 2026-04-17 +updated: 2026-04-17 +--- + +# Hosting the Agent SDK in Production + +The Claude Agent SDK is **not stateless** — it runs a persistent shell process that executes commands and manages files. This makes hosting it fundamentally different from calling a REST API. + +## System Requirements + +| Resource | Minimum | +|----------|---------| +| Runtime | Python 3.10+ **or** Node.js 18+ | +| Node.js | Always required (SDK spawns Claude Code CLI internally; bundled, no separate install) | +| RAM | 1 GiB recommended | +| Disk | 5 GiB recommended | +| CPU | 1 core recommended | +| Network | Outbound HTTPS to `api.anthropic.com`; optional MCP server access | + +## Sandbox Provider Options + +Managed container sandboxes purpose-built for AI code execution: + +- **Modal Sandbox** — has demo implementation (Slack gif creator) +- **Cloudflare Sandboxes** — open-source `sandbox-sdk` +- **Daytona** +- **E2B** +- **Fly Machines** +- **Vercel Sandbox** + +For self-hosted isolation (Docker, gVisor, Firecracker) see the Secure Deployment guide. + +## Deployment Patterns + +### Pattern 1: Ephemeral Sessions +New container per task, destroyed on completion. Best for one-off tasks. + +- Bug investigation & fix +- Invoice/document processing +- Translation batches +- Image/video transformations + +### Pattern 2: Long-Running Sessions +Persistent containers, often running multiple Claude Agent processes per container. Best for proactive agents that act without user input. + +- Email triage agent +- Per-user site builder (exposes container ports) +- High-frequency chatbots (Slack, etc.) + +### Pattern 3: Hybrid Sessions +Ephemeral containers hydrated from a database or SDK session resumption. Best for intermittent-interaction workflows. + +- Personal project manager with context persistence +- Deep multi-hour research (save, resume) +- Multi-turn customer support tickets + +### Pattern 4: Single Container, Multiple Agents +Multiple SDK processes share one container. Least common — requires coordination to prevent agents overwriting each other. + +- Agent simulations (games, multi-agent environments) + +## Key Operational Notes + +- **Communication**: Expose HTTP/WebSocket ports from within the container to reach SDK instances externally. +- **Cost**: Tokens dominate; container overhead starts ~$0.05/hr minimum depending on provider. +- **Idle shutdown**: Tune idle timeout per provider based on expected user response cadence. +- **CLI versioning**: Claude Code CLI uses semver — breaking changes are versioned, minor updates are safe to auto-apply. +- **Monitoring**: Containers are standard servers — use your existing backend logging infrastructure. +- **Session timeout**: No hard timeout, but set `maxTurns` to prevent infinite loops. + +## Key Takeaways + +- SDK runs as a **long-running process**, not a stateless call — it needs a persistent container environment. +- Choose deployment pattern based on task lifetime: ephemeral (one-off) → long-running (proactive) → hybrid (intermittent) → single-container multi-agent (collaboration). +- Every instance needs Node.js even for Python SDK (Claude Code CLI is bundled). +- Minimum recommended specs: 1 GiB RAM, 5 GiB disk, 1 CPU. +- Use `maxTurns` to guard against infinite agent loops. +- Standard backend observability (logs, metrics) works as-is — containers are just servers. + +## Related Articles + +- [[wiki/agent-sdk/configure-permissions|Configure Permissions]] — control what tools agents can use inside containers +- [[wiki/agent-sdk/hooks-guide|Hooks Guide]] — automate container lifecycle events +- [[wiki/agent-sdk/mcp-integration|MCP Integration]] — extend agents with external tool servers +- [[wiki/agent-sdk/user-input-approvals|User Input & Approvals]] — handle human-in-the-loop approvals in hosted agents +- [[wiki/architecture/docker-compose|Docker Compose Patterns]] — self-hosted container orchestration + +## Sources + +- `raw/Hosting the Agent SDK.md`