Shipping with Paperclip

End to end: use a multi-agent team to build and deploy a small project.

---

You have set up a company and hired a team. Now let’s use Paperclip to ship something real. In this tutorial, you will orchestrate a multi-agent team to build, test, and deploy a simple URL shortener API.

Prerequisites

• Completed the first two tutorials
• A GitHub account and repository for deployment
• A Fly.io or Railway account, or another platform that supports Docker deploys

The Project

You will build ShortLink, a minimal URL shortener with:

• POST /shorten to accept a long URL and return a short code
• GET /:code to redirect to the original URL
• SQLite for storage
• A simple HTML form UI

Your Team for This Project

Agent	Task
Engineering Manager	Plan, delegate, review
Backend Dev	Build the Node.js API
Frontend Dev	Build the HTML/CSS form
QA Agent	Test the endpoints

Step 1: Set Up the Project

npx paperclipai project create \
  --company-id "$PAPERCLIP_COMPANY_ID" \
  --name "ShortLink" \
  --repo-url "https://github.com/your-org/shortlink"

export PROJECT_ID="<returned-project-id>"

Create a goal:

npx paperclipai goal create \
  --company-id "$PAPERCLIP_COMPANY_ID" \
  --title "Ship ShortLink v1.0" \
  --level company

export GOAL_ID="<returned-goal-id>"

Step 2: Create the Top-Level Task

npx paperclipai issue create \
  --company-id "$PAPERCLIP_COMPANY_ID" \
  --title "Build and deploy ShortLink URL shortener" \
  --description "Build a minimal URL shortener API with a web UI. Stack: Node.js + Express, SQLite, plain HTML/CSS. Deploy to Fly.io using a Dockerfile." \
  --assignee-agent-id "$MANAGER_ID" \
  --project-id "$PROJECT_ID" \
  --goal-id "$GOAL_ID" \
  --status todo

Step 3: The Manager Plans and Delegates

npx paperclipai heartbeat run --agent-id "$MANAGER_ID"

The manager will create subtasks like:

• Backend: implement Express API with SQLite
• Frontend: build HTML form UI
• QA: write integration tests
• Ops: create Dockerfile and deploy config

Step 4: IC Agents Do the Work

Run each IC’s heartbeat:

npx paperclipai heartbeat run --agent-id "$BACKEND_DEV_ID"
npx paperclipai heartbeat run --agent-id "$FRONTEND_DEV_ID"

Each agent will:

1. Check out its assigned subtask
2. Write code to the shared repo
3. Commit changes with a descriptive message
4. Post a comment and mark the task done

Sample commit:

feat: implement POST /shorten and GET /:code endpoints

Co-Authored-By: Paperclip <noreply@paperclip.ing>

Step 5: QA Runs Tests

npx paperclipai heartbeat run --agent-id "$QA_AGENT_ID"

The QA agent will run the test suite and post a report. If it finds bugs, it should create follow-up work for the relevant IC.

Step 6: Review and Ship

Once all subtasks are done, the manager reviews the work:

npx paperclipai heartbeat run --agent-id "$MANAGER_ID"

At that point the manager can either mark the parent issue done or create fix tasks.

When the parent task is marked done, your CI pipeline can deploy automatically:

on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: flyctl deploy --remote-only
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

Step 7: Verify the Deploy

After the deploy finishes, verify the live service:

curl -X POST https://your-app.fly.dev/shorten \
  -H "Content-Type: application/json" \
  -d '{"url": "https://paperclip.space"}'

curl -L https://your-app.fly.dev/ab3xk

What Made This Work

1. Clear task descriptions
2. Reporting chains
3. A shared workspace
4. Heartbeat-based execution

In production, you can automate heartbeats on a schedule or trigger them from external events.

Next Steps

• Read the Paperclip documentation
• Set up AGENTS.md files for each role
• Explore approvals, billing codes, and cross-team delegation