agent-builder/skills/agent-system-design/references/deployment-targets.md

Deployment Targets

Reference for the agent-system-design skill. Covers the four deployment platforms available for Claude Code agents. Use this to guide target selection and scaffold the correct infrastructure files.

---

1. Local (cron/launchd)

How it works: Claude Code CLI invoked by the host scheduler. No persistent process; each run starts a fresh Claude Code session and exits.

Setup files to scaffold:

• automation.sh -- wrapper script that sets env vars and invokes claude
• Cron entry comment block in README, or launchd.plist for macOS

Cron pattern:

0 5 * * * /path/to/project/automation.sh >> /var/log/agent.log 2>&1

launchd pattern (macOS):

<key>StartCalendarInterval</key>
<dict>
  <key>Hour</key><integer>5</integer>
  <key>Minute</key><integer>0</integer>
</dict>

Pros:

• Simple setup, no infrastructure cost
• Full tool access (filesystem, shell, MCP)
• Easy to test locally before any deployment

Cons:

• Not always-on between scheduled runs
• No mobile access without a channel plugin
• Log rotation must be managed manually

Best for: Development, testing, personal daily pipelines (nightly batch, ecosystem pulse).

---

2. Mac Mini (launchd + channels)

How it works: A dedicated Mac runs Claude Code inside a persistent tmux session. launchd ensures the session restarts on reboot. Channel plugins (iMessage, Telegram) provide mobile access.

Setup files to scaffold:

• launchd.plist -- keeps the tmux session alive across reboots
• tmux-start.sh -- creates/attaches the named session
• .mcp.json -- channel MCP server (Telegram or iMessage)
• channels-guide.md -- instructions for mobile interaction

tmux session pattern:

tmux new-session -d -s agent -x 220 -y 50
tmux send-keys -t agent "claude --model claude-sonnet-4-6" Enter

Pros:

• Always-on between scheduled runs
• Native iMessage support (macOS-only feature)
• Full GUI access for Computer Use (Desktop app)
• Local hardware, no cloud dependency

Cons:

• Requires dedicated physical hardware
• iMessage and Computer Use are macOS-only
• Single machine; no horizontal scaling

Best for: Personal always-on agent with phone access, Computer Use workflows, home automation pipelines.

---

3. VPS (systemd + cron)

How it works: Linux server runs Claude Code headless. systemd manages the service lifecycle. Cron handles scheduled tasks. Telegram or Slack provides the channel layer.

Setup files to scaffold:

• systemd/agent.service -- service unit for the agent process
• systemd/agent.timer -- timer unit for scheduled runs (alternative to cron)
• automation.sh -- invocation wrapper
• .mcp.json -- Telegram or Slack MCP server
• channels-guide.md -- instructions for team interaction

systemd service pattern:

[Service]
ExecStart=/path/to/automation.sh
Restart=on-failure
User=agent
Environment=HOME=/home/agent

systemd timer pattern:

[Timer]
OnCalendar=*-*-* 05:00:00
Persistent=true

Pros:

• True always-on with automatic restart on failure
• Scalable: multiple agents on one server or across servers
• Team access via shared Telegram/Slack channel
• No hardware to manage locally

Cons:

• No iMessage (Linux)
• No Computer Use (no display server in headless mode)
• Requires server management (security patches, disk, logs)

Best for: Server-side agents, team pipelines, production workloads, nightly batch that must run reliably even when the developer's laptop is off.

---

4. Managed Agents (Anthropic API)

How it works: Anthropic hosts the agent runtime. The builder deploys via the /v1/agents and /v1/sessions REST API, or uses @anthropic-ai/sdk in TypeScript/Python. No local Claude Code installation required.

Setup files to scaffold:

• agent.ts or agent.py -- SDK code defining the agent
• sessions.ts -- session management helpers
• .env.template -- API key template
• README.md -- deployment and configuration instructions

TypeScript pattern:

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const session = await client.sessions.create({ agent_id: "ag_..." });

Pros:

• Cloud-native, zero infrastructure to manage
• Scales automatically across sessions
• Persistent sessions via the API
• Integrates directly into SaaS products or APIs

Cons:

• Different architecture from Claude Code CLI (no local filesystem by default)
• API costs per token, no flat rate
• Less direct filesystem access than CLI agents
• Feature set tied to what the Managed Agents API exposes

Best for: Production deployment at scale, SaaS product integration, agents that must be accessible to end users without CLI access.

---

Comparison Matrix

Dimension	Local (cron)	Mac Mini	VPS	Managed API
Always-on	No	Yes	Yes	Yes
Computer Use	No	Yes (Desktop)	No	No
iMessage	No	Yes	No	No
Telegram/Slack	Via MCP	Via MCP	Via MCP	Via integration
Infrastructure cost	Zero	Hardware	VPS fee	API token cost
Setup complexity	Low	Medium	Medium	Low (SDK)
Team access	No	Limited	Yes	Yes
Filesystem access	Full	Full	Full	Limited
Horizontal scaling	No	No	Manual	Automatic
Best environment	Dev/test	Personal	Team/prod	SaaS/prod

Scaffold Decision Guide

1. Is this a personal agent for one developer? Start with Local. Upgrade to Mac Mini if always-on or iMessage is required.

2. Does the agent need Computer Use? Mac Mini with Claude Code Desktop is the only option today. Document this constraint if the user is on Linux or Windows.

3. Is this a team or production workload? VPS with systemd. Add Telegram/Slack channel.

4. Is this going into a product or SaaS? Managed API. Scaffold TypeScript SDK code, not a CLAUDE.md agent.

5. Do not mix targets in one scaffold. Pick one. Document the alternatives in the ## Deployment section of the generated README.