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):**
```xml
<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:**
```bash
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:**
```ini
[Service]
ExecStart=/path/to/automation.sh
Restart=on-failure
User=agent
Environment=HOME=/home/agent
```

**systemd timer pattern:**
```ini
[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:**
```typescript
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.