← All articles

Before you start

You need:

• A running Paperclip instance (local or hosted)
• An Anthropic API key (get one at console.anthropic.com)
• 20 minutes

If you don't have Paperclip running yet, the fastest path is Railway with the $20 free credit — deploy takes about 5 minutes.

Step 1: Admin setup

On first access to your Paperclip instance, the setup wizard prompts you to:

1. Create an admin account (email + password)
2. Set up your company (name, description)
3. Configure basic settings

Complete this before creating agents. Your admin account is the "board" — the human who reviews and directs agent work.

Step 2: Create your first agent

Go to Agents → New Agent. Fill in:

• Name: Something descriptive. Start with a role: "Research Agent" or "Writer".
• Role: Select the appropriate role (or leave as contributor for a general-purpose agent)
• Adapter type: claude_local (recommended)
• Model: claude-sonnet-4-6 (good balance of quality and cost)

For the adapter config, set:

{
  "model": "claude-sonnet-4-6",
  "maxTurnsPerRun": 100
}

Save the agent.

Step 3: Add an API key

Your agent needs an Anthropic API key to call Claude:

1. Go to your new agent's settings
2. Find Secrets or API Keys
3. Add ANTHROPIC_API_KEY with your key from console.anthropic.com
4. Save

The key is stored encrypted. Without this step, the agent will fail to run.

Step 4: Write the agent's instructions

Instructions (AGENTS.md) tell the agent what it does and how to behave. A minimal but effective instructions file:

# Research Agent — [Your Company Name]

You research topics and write structured summaries.

## What you do

When assigned a research task:
1. Read the task description to understand what's being asked
2. Use web search to find relevant, current information
3. Read the top 3–5 sources
4. Write a 300–500 word summary with the key findings
5. Include links to your sources
6. Mark the task as done

## How to format your output

- Start with a 2-sentence summary of the main finding
- Use H2 sections for major themes
- Bullet points for lists
- Always cite your sources

## When you get stuck

If the task is unclear or you need more information to proceed:
- Add a comment asking the specific question
- Mark the task as blocked
- Wait for a response before continuing

Upload or link this file as the agent's instructions path.

Step 5: Configure the heartbeat

In the agent's runtime settings:

{
  "heartbeat": {
    "enabled": true,
    "intervalSec": 3600,
    "wakeOnDemand": true,
    "maxConcurrentRuns": 1
  }
}

• intervalSec: 3600 — checks for work hourly
• wakeOnDemand: true — also wakes immediately when you assign a task
• maxConcurrentRuns: 1 — one run at a time (important for starters)

Save and set the agent status to Running.

Step 6: Assign your first task

Go to Issues → New Issue and create a research task:

Title: Research: best practices for writing effective API documentation

Description:
Research and summarize best practices for writing API documentation.
Focus on:
- What makes API docs good vs. bad (specific examples)
- Structure and navigation patterns
- Code examples and interactive elements
- Common mistakes to avoid

Target: 400-500 words, with source links.

Set:

• Assignee: Your research agent
• Status: Todo

Save the task. If wakeOnDemand is enabled, the agent should start within a few minutes.

Step 7: Watch the agent work

In the issue view, you'll see:

1. Status changes to in_progress when the agent starts
2. Comments appear as the agent works (depending on your agent's instruction style)
3. Status changes to done when the task is complete

Check the agent's run history (Agent → Runs) to see:

• When the run started and finished
• How many tokens were used
• Any errors

Step 8: Review the output

Read what the agent produced. Ask yourself:

• Did it answer the actual question?
• Is the format right?
• Are the sources real and relevant?
• What would you change?

If the output is off: update the instructions to be more specific about what you want, then assign a similar task and compare.

What happens next

After a successful first task:

1. Improve instructions based on what was missing or wrong
2. Assign more tasks to build a pattern
3. Add a second agent for a different function (writing, coding, support)
4. Set up a routine if you have recurring tasks (weekly reports, daily briefs)

The first task is rarely perfect. The fourth task, after a few instruction improvements, usually is. That's the normal trajectory.

Troubleshooting

Agent doesn't pick up the task:

• Check that the agent is set to Running (not Paused)
• Verify wakeOnDemand: true in heartbeat config
• Check the Runs tab for errors

Run fails immediately:

• Check the API key is set correctly
• Test the key: curl https://api.anthropic.com/v1/messages -H "x-api-key: YOUR_KEY" ...

Agent seems stuck:

• Check the Runs tab — is a run in progress?
• If it's been over 30 minutes, check logs for errors
• A hung run usually means the agent hit a timeout or an unexpected error

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.