microsoft/amplifier-app-paperclip

microsoft/amplifier-app-paperclip

Description: Paperclip with Amplifier Agent integration

Language: TypeScript

License: MIT

Stars: 0

Forks: 0

Open issues: 1

Created: 2026-06-04T21:13:41Z

Pushed: 2026-06-08T19:43:04Z

Default branch: main

Fork: no

Archived: no

README:

amplifier-app-paperclip

Setting up paperclip with the `amplifier_local` adapter, which lets paperclip agents run on the Amplifier engine.

The adapter is integrated at the same depth as paperclip's built-in claude_local and codex_local adapters — same UI, same session lifecycle, same observability. The only differences are which engine binary the heartbeat invokes (amplifier-agent instead of claude / codex) and what models are available.

Prerequisites

• A non-root user — paperclip uses an embedded PostgreSQL that refuses to run as root. Create or switch to a normal user account before continuing.
• Node 18+ (Node 22 LTS recommended)
• pnpm 9+ (npm install -g pnpm@latest)
• git
• uv for installing the engine (curl -LsSf https://astral.sh/uv/install.sh | sh)
• amplifier-agent >= 0.5.1, installed *as the same user that will run paperclip*. The paperclip server invokes amplifier-agent per turn and inherits the user's PATH to find both amplifier-agent and uv. Installing as a different user (e.g. root) silently breaks heartbeats:

uv tool install --reinstall --force git+https://github.com/microsoft/amplifier-agent@v0.5.1
# ensure ~/.local/bin is on PATH; verify:
amplifier-agent version --json # → {"version":"0.5.1","protocolVersion":"0.3.0"}

• An LLM provider API key for the model you'll use (e.g. ANTHROPIC_API_KEY for Claude, OPENAI_API_KEY for GPT). The key is set per-agent in the paperclip UI, not in your host shell.

Quick start

git clone https://github.com/microsoft/amplifier-app-paperclip
cd amplifier-app-paperclip
pnpm install

# Optional but recommended: export provider API keys in this shell
# BEFORE starting the server. Every `amplifier_local` agent you create
# later will inherit these automatically (whitelisted vars only —
# see "Configure your agent's API key" below for the full list).
export ANTHROPIC_API_KEY=sk-ant-... # for claude-* models
export OPENAI_API_KEY=sk-... # for gpt-* / o3-* / o4-* models
# Add only the keys for providers you actually use.

pnpm paperclipai onboard --yes # one-time: creates board user + Agent JWT secret, then runs the server

onboard --yes combines initial setup and pnpm dev. For subsequent runs (after the first onboarding) use pnpm dev directly — but remember to re-export the keys in that shell, otherwise the server starts without them.

Open http://127.0.0.1:3100 — look for amplifier_local in the adapter type dropdown when creating or editing an agent. (The server binds to 127.0.0.1 only; if you need to reach it from another machine, set up an SSH tunnel or reverse proxy.)

If you skipped the export step or want different keys per agent, set them per-agent via the UI instead — see [Configure your agent's API key](#configure-your-agents-api-key) below. Both paths work; per-agent values override the host-shell values on collision.

Verifying it works

After the dev server reports it's listening, sanity-check from another terminal:

# 1. Health: status ok, bootstrap ready
curl -s http://127.0.0.1:3100/api/health | jq

# 2. Adapter is loaded
curl -s http://127.0.0.1:3100/api/adapters \
| jq '.[] | select(.type=="amplifier_local")'
# expect: {"type":"amplifier_local","loaded":true,"disabled":false,"modelsCount":11,…}

# 3. Engine version (per-user, must match the user running paperclip)
amplifier-agent version --json
# expect: {"version":"0.5.1","protocolVersion":"0.3.0"}

Note: /api/health returns authReady: true even *before* onboarding has run, so health alone is not a sufficient check. The dev-server console banner shows Agent JWT: set once onboarding has completed — that's the authoritative signal. If you see Agent JWT: missing, re-run pnpm paperclipai onboard --yes.

Once you've configured an agent (see next section) and triggered its first heartbeat, the run log under ~/.paperclip-worktrees/instances//data/runs// should contain:

• zero Skipping symlink that escapes skill directory boundary lines
• zero No approval provider registered, auto-denying lines
• zero 'dict' object has no attribute 'approved' lines
• zero Cannot initialize without orchestrator lines
• one or more [paperclip] Materialized amplifier-local skill "" lines on the first run

GET /api/agents//runtime-state should report lastRunStatus: "succeeded".

Configure your agent's API key

The amplifier_local adapter reads provider API keys from two sources, in this precedence:

1. Per-agent — set in the agent's edit form (Agent Environment Run Variables). Wins on collision. 2. Host shell of the paperclip server — exported in the shell where pnpm dev runs. Whitelisted to known provider keys only. Each inherited key emits a [paperclip] Inherited from host environment line in the run log for provenance.

Pick whichever fits. Host-shell inheritance is the common case for single-user dev. Per-agent is required for multi-tenant deployments where each agent needs distinct credentials.

The whitelist (the only env vars the adapter inherits from the paperclip server's shell):

| Adapter model | Required key | |---|---| | claude-* (Anthropic) | ANTHROPIC_API_KEY | | gpt-*, o3-*, o4-* (OpenAI) | OPENAI_API_KEY | | gpt-* via Azure | AZURE_OPENAI_API_KEY (+ AZURE_OPENAI_ENDPOINT) | | gemini-* (Gemini) | GEMINI_API_KEY | | llama*, qwen*, etc. (Ollama) | OLLAMA_HOST (e.g. http://localhost:11434) |

Any other env vars in the paperclip shell (e.g. DATABASE_URL, AWS_SECRET_ACCESS_KEY, PATH) are never passed through to agents.

Option A — Host shell (simplest, single-user dev)

export ANTHROPIC_API_KEY=sk-...
pnpm dev

Every amplifier_local agent automatically picks up the key. Confirm it landed by checking a run log for [paperclip] Inherited ANTHROPIC_API_KEY from host environment.

Option B — Per-agent (multi-tenant, or when you need distinct keys per agent)

1. Create or open an agent that uses amplifier_local. 2. In the agent's edit form, find the Agent Environment Run Variables section. 3. Add a…