Paperclip on AWS — Knowtation video factory
This directory contains everything needed to stand up Paperclip (the open-source agent orchestrator) on an AWS t3.medium instance, wire it to your Knowtation hosted Hub via MCP, and run the 22-agent video factory across Born Free, Store Free, and Knowtation.
You should not be reading this directly. Follow docs/marketing-internal/RUNBOOK-VIDEO-FACTORY-2026-04-30.md — this README is the agent-facing reference for what's in each sub-directory.
Layout
deploy/paperclip/
├── README.md # this file
├── terraform/ # AWS infra (EC2, security group, IAM role, SSM)
│ ├── main.tf # primary resources
│ ├── variables.tf # tunables (region, instance type, your home IP)
│ ├── outputs.tf # public IP, instance ID, Tailscale join URL
│ └── versions.tf # provider version pins
├── install.sh # one-shot: Node 20 + pnpm + Postgres 16 + Paperclip + nginx + LE
├── scripts/ # operator scripts run AFTER install.sh
│ ├── push-secrets.sh # interactive: pushes secrets to AWS SSM
│ ├── hello-world-test.sh # smoke-tests Paperclip can talk to DeepInfra
│ ├── wire-knowtation-mcp.sh # adds hosted Knowtation MCP endpoint
│ ├── load-skills-and-agents.sh # imports skills/* and agents/* into Paperclip
│ └── run-controller.sh # triggers the controller agent for all 3 projects
├── skills/ # 5 reusable Knowtation skills (Node 20 .mjs modules)
│ ├── read-style-guide.mjs # pulls vault/projects/<project>/style-guide/voice-and-boundaries.md
│ ├── read-positioning.mjs # pulls vault/projects/<project>/outlines/positioning-and-messaging-2026-04.md
│ ├── read-playbook.mjs # pulls any vault/projects/<project>/playbooks/<slug>.md
│ ├── search-vault.mjs # semantic search scoped to one project
│ └── write-draft.mjs # writes drafts back to vault with frontmatter
└── agents/ # 22 agent definitions (YAML)
├── controller/
│ └── controller.yaml # orchestrates 18 per-project agents in parallel
├── bornfree/ # 6 conveyor-belt agents for Born Free
│ ├── script-writer.yaml
│ ├── social-poster.yaml
│ ├── thumbnail-brief.yaml
│ ├── clip-factory.yaml
│ ├── blog-seo.yaml
│ └── newsletter.yaml
├── storefree/ # 6 for Store Free (mirror structure)
├── knowtation/ # 6 for Knowtation (mirror structure)
└── bridges/ # 3 SaaS bridge agents
├── heygen-render.yaml
├── elevenlabs-tts.yaml
└── descript-import.yaml
Tests
All testable code in this tree is unit-tested under test/paperclip-*.test.mjs at the repo root. Per Aaron's Rule #0, no agent or skill ships to the AWS box unless its test passes locally first.
test/paperclip-knowtation-skills.test.mjs— unit tests for the 5 skillstest/paperclip-agent-fixtures.test.mjs— fixture tests for the 7 agent promptstest/paperclip-bridges.test.mjs— mocked API tests for HeyGen, ElevenLabs, Descript
Run: pnpm test paperclip
Secrets, never committed
The Terraform creates an SSM Parameter Store namespace at /knowtation/paperclip/*. Every secret lives there:
/knowtation/paperclip/DEEPINFRA_API_KEY/knowtation/paperclip/HEYGEN_API_KEY/knowtation/paperclip/HEYGEN_AVATAR_ID/knowtation/paperclip/HEYGEN_VOICE_ID/knowtation/paperclip/ELEVENLABS_API_KEY/knowtation/paperclip/ELEVENLABS_VOICE_ID/knowtation/paperclip/DESCRIPT_API_KEY/knowtation/paperclip/DESCRIPT_BORNFREE_PROJECT_ID/knowtation/paperclip/DESCRIPT_STOREFREE_PROJECT_ID/knowtation/paperclip/DESCRIPT_KNOWTATION_PROJECT_ID/knowtation/paperclip/KNOWTATION_HUB_URL/knowtation/paperclip/KNOWTATION_HUB_JWT/knowtation/paperclip/KNOWTATION_VAULT_ID
The EC2 instance has an IAM role with read-only access to this namespace. Paperclip's systemd service reads the parameters at startup and re-reads them every 60 seconds (so JWT rotation is hot — no restart required).
Costs
| Resource | Monthly cost |
|---|---|
| EC2 t3.medium (2 vCPU, 4 GB RAM) | $30.37 |
| EBS gp3 30 GB | $2.40 |
| SSM Parameter Store (Standard) | $0.00 (free tier covers 10k params) |
| Data egress | <$1 (mostly inbound webhook traffic) |
| Total AWS | ~$33/mo |
This is the orchestration layer only. The video factory's full bill including all SaaS is ~$140-195/mo (see runbook for breakdown).