Hermes + Paperclip Client Activation Checklist

How to use this page

Run it live during internal install work

Internal operations checklist for creating client installs of Hermes Agent and Paperclip. Clients may see this during the install call, but it is written for the internal installer/operator. Keep terminal commands visible and run them live as verification points. Tailscale/private-network access is a default requirement so the installer can support and maintain the environment after handoff.

Work through the four SAGE phases: Scope → Automate → Generate → Evaluate. Tick items as they are confirmed. Pause whenever client approval, credential entry, OAuth, payment, or public exposure is involved.

Security rule: do not ask for raw card details or passwords in chat or shared docs. The client should approve signups, payments, OAuth prompts, and credential entry directly.

Operator note: keep command blocks visible. Copy terminal commands directly when appropriate, and record final URLs, Tailscale IPs, restart commands, credential locations, output folders, and open risks before handoff.

SAGE Phase 1

1. Scope

Clarify the install target, accounts, access, safety rules, defaults, and maintenance path before changing the machine. Tailscale/private access is treated as a standard part of the install so internal ops can provide upkeep later.

Installation goal Pre-install decisions Client prerequisites Accounts and access Local information Security expectations Target machine requirements Internal/client account setup Tailscale-first remote access default Threat model, permissions, and approvals

Client prerequisites

Ask the client to prepare these before the session.

Local information

Client organization name. Primary business objective for the first agent team. Names and roles for initial agents. Safe operating rules, especially approval gates for outbound actions. Preferred admin contact for alerts. Where installation notes should be saved.

Security expectations

Confirm secrets must not be pasted into shared documents or chat transcripts. Confirm whether credentials can be entered interactively by the client. Confirm whether the installer may store credentials in .env, OAuth token files, or platform-specific secret stores. Confirm backup expectations for Paperclip data. Confirm whether the install must satisfy any internal compliance requirements.

Internal/client account setup

Confirm the agent/team naming convention for this client install. Name the primary agent CEO/operator. Create or confirm the dedicated Gmail/Google account if the install needs email, Drive, Docs, Sheets, Calendar, or OAuth ownership. Save recovery email and phone details in the approved password manager or client-owned secret store. Sign into Gmail in the browser and confirm it can send and receive a test message. Create or confirm the dedicated GitHub account if repositories will be connected. Add SSH key to GitHub where needed. Verify GitHub SSH auth:

git ls-remote git@github.com:OWNER/REPO.git

Create or confirm Vercel account if generated projects will deploy there. Create or confirm Cloudflare account if DNS, Pages, tunnels, or public hostnames are required. Create or confirm OpenAI/ChatGPT/Codex, OpenRouter, Anthropic, Nous Portal, or other model-provider accounts. Store credentials in the approved password manager, .env, OAuth token store, or client-owned secret store — never in the checklist.

Tailscale-first remote access default

Confirm the installer will have ongoing Tailscale/private-network access for upkeep unless the client explicitly declines. Install Tailscale on the target machine or VPS. Authenticate the target into the right Tailscale network/tailnet. Install Tailscale on the installer/admin machine if not already present. Confirm both devices appear in the Tailscale admin dashboard. Record the target Tailscale IP in handoff notes. Verify SSH over Tailscale:

ssh USER@100.x.x.x

If dashboards are loopback-only, verify SSH port forwarding over Tailscale:

ssh -L 9119:127.0.0.1:9119 -L 3100:127.0.0.1:3100 USER@100.x.x.x

Confirm the installer can reach Hermes and Paperclip dashboards from the maintenance machine.

Threat model, permissions, and approvals

Confirm what Hermes and Paperclip are allowed to access. Confirm whether generated outputs may contain private client data. Confirm whether dashboards should be Tailscale-only, private-network-only, loopback-only, or public HTTPS behind authentication. Confirm whether the install may send emails, publish files, deploy websites, trigger external actions, or spend API credits. Confirm who approves outbound sends, public publishing, purchases, production deploys, and client-facing promises. Confirm logging expectations and where logs may be stored. Confirm backup expectations for Paperclip data, Hermes config, sessions, and generated artifacts. Confirm spending limits for model/API providers. Discuss key risks: prompt injection from webpages/emails/docs/uploads, credential exposure, runaway automation, public dashboard exposure, and generated files containing private data.

SAGE Phase 2

2. Automate

Install Hermes and Paperclip, configure required tools and integrations, expose dashboards through the approved private path, and prove the two systems can run useful automation safely.

Environment preparation Hermes installation Hermes configuration checklist Optional Hermes messaging gateway setup Paperclip installation Start and verify Paperclip Recommended Paperclip helper commands Create the first Paperclip organization Optional Codex-backed Paperclip agents Hermes + Paperclip operating configuration Dashboard access and Hermes + Paperclip connection Tools and integrations

Environment preparation

Run these checks before installation.

Confirm current user and privilege level:

whoami
id
sudo -v

Confirm operating system:

uname -a
cat /etc/os-release

Confirm core tools:

git --version
python3 --version
node --version || true
npm --version || true
curl --version

Update packages using the operating system’s normal package manager. Install missing prerequisites. Create a working directory for notes and install logs. Decide where Hermes and Paperclip runtime data will live. Confirm backups or snapshots are available before changing an existing production host.

Hermes installation

Hermes is installed first because it becomes the operator interface for the rest of the setup.

Install Hermes using the official install script:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Open a new shell or load the updated shell path. Confirm the CLI is available:

hermes --version

Run the guided setup:

hermes setup

Configure the model/provider during setup. Add required credentials through the setup wizard or auth command:

hermes auth

Confirm the model can answer a simple query:

hermes chat -q "Reply with: Hermes is working."

Run the health check:

hermes doctor

Fix any missing dependencies or configuration warnings.

Hermes configuration checklist

Complete the Hermes configuration before connecting external systems.

Confirm the active config path:

hermes config path

Confirm the environment/secrets path:

hermes config env-path

Confirm configured provider and model:

hermes config

Enable only the toolsets the client needs.

hermes tools list
hermes tools

Recommended initial toolsets for a client operator install:

terminal file web/search if online research is required browser if web-app interaction is required cronjob if scheduled work is required messaging if gateway delivery is required kanban if multi-agent work queues are required Confirm memory settings are appropriate for the client. Confirm secret redaction remains enabled unless there is a deliberate debugging reason to disable it. Confirm command approvals are set to the desired level. Save a short note describing which model/provider and toolsets were selected.

Optional Hermes messaging gateway setup

Skip this section if the client will use Hermes only from the terminal.

Decide which platform will be the primary operator channel. Collect the required bot/app credentials from the client. Run the gateway setup:

hermes gateway setup

Start the gateway in the foreground for the first test:

hermes gateway run

Send a test message from the chosen platform. Confirm Hermes replies in the correct chat/channel. If the client wants the gateway always on, install or start it as a service:

hermes gateway install
hermes gateway status

Document the restart command:

hermes gateway restart

Verify the gateway logs location:

ls ~/.hermes/logs/

Verification:

Client can send a message to Hermes. Hermes responds from the expected model/profile. Tool approvals or denials work as expected on that platform. Gateway restarts cleanly.

Paperclip installation

Paperclip should not run as root when using its embedded PostgreSQL. Create a dedicated runtime user.

Choose the Paperclip install path. Recommended:

/opt/paperclip

Clone Paperclip:

sudo git clone --depth 1 https://github.com/paperclipai/paperclip.git /opt/paperclip

Create a non-root runtime user:

sudo id paperclip 2>/dev/null || sudo useradd -m -s /bin/bash paperclip
sudo chown -R paperclip:paperclip /opt/paperclip

Enable Corepack and activate the expected pnpm version:

cd /opt/paperclip
sudo corepack enable
sudo corepack prepare pnpm@9.15.4 --activate

Install dependencies as the Paperclip runtime user:

sudo runuser -u paperclip -- bash -lc 'cd /opt/paperclip && pnpm install'

Run first-time onboarding as the Paperclip runtime user:

sudo runuser -u paperclip -- bash -lc 'cd /opt/paperclip && pnpm paperclipai onboard --yes --bind loopback'

Expected important paths:

/home/paperclip/.paperclip/instances/default/config.json
/home/paperclip/.paperclip/instances/default/db

Save the config path in the handoff notes. Confirm the client understands whether the instance is loopback-only, private-network-only, or public.

Start and verify Paperclip

Start Paperclip as the runtime user:

sudo runuser -u paperclip -- bash -lc 'cd /opt/paperclip && pnpm dev:once'

For a long-running install, start it through a service, tmux session, or helper script rather than leaving it tied to a temporary SSH session.

Verify the health endpoint:

curl -sS --max-time 5 http://127.0.0.1:3100/api/health

Expected result includes a healthy status such as:

{"status":"ok"}

Verify the API can list companies:

curl -sS --max-time 5 http://127.0.0.1:3100/api/companies

Open the UI from the approved network path:

http://127.0.0.1:3100

or the client’s configured private/public URL.

Verification:

Paperclip server starts without root/PostgreSQL errors. /api/health returns healthy status. /api/companies responds. UI loads in the browser. Logs do not show new startup errors.

Recommended Paperclip helper commands

Create helper commands so the client can start, stop, and inspect Paperclip after handoff.

Create paperclip-start:

sudo tee /usr/local/bin/paperclip-start >/dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
cd /opt/paperclip
exec runuser -u paperclip -- bash -lc 'cd /opt/paperclip && pnpm dev:once'
EOF

Create paperclip-stop:

sudo tee /usr/local/bin/paperclip-stop >/dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
cd /opt/paperclip
exec runuser -u paperclip -- bash -lc 'cd /opt/paperclip && pnpm dev:stop || true'
EOF

Create paperclip-status:

sudo tee /usr/local/bin/paperclip-status >/dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
curl -sS --max-time 5 http://127.0.0.1:3100/api/health || true
printf '\n'
runuser -u paperclip -- bash -lc "cd /opt/paperclip && pnpm dev:list" || true
EOF

Make helpers executable:

sudo chmod +x /usr/local/bin/paperclip-start /usr/local/bin/paperclip-stop /usr/local/bin/paperclip-status

Verify helpers:

paperclip-status

Create the first Paperclip organization

Use the UI if the client prefers a guided experience. Use the local API for repeatable setup in trusted loopback mode.

Create a company/organization. Record the company ID. Add the first project or operating area. Add initial agents only after their responsibilities and approval gates are clear. If agents are placeholders, do not assign executable work to them yet. If agents are real execution agents, verify their adapter before assigning work.

Example local trusted API flow:

curl -sS -X POST http://127.0.0.1:3100/api/companies \
  -H 'Content-Type: application/json' \
  --data-binary '{"name":"Client Agent Team","description":"Initial client Paperclip organization.","budgetMonthlyCents":0}'

For a safe placeholder Hermes CEO/operator agent, use a process adapter that prints a harmless heartbeat rather than executing real work.

Checklist:

Organization name is correct. Organization purpose is clear. Initial projects are visible. Agents have accurate names, roles, and responsibilities. Agents include explicit safety rules. No unapproved outbound actions are enabled.

Optional Codex-backed Paperclip agents

Only complete this section if the client wants Paperclip agents to execute work through local Codex.

Install Codex globally:

sudo npm install -g @openai/codex

Verify Codex is available to the Paperclip runtime user:

sudo runuser -u paperclip -- bash -lc 'codex --version'

sudo runuser -u paperclip -- bash -lc 'codex login --device-auth'

Ask the client to complete the device login in their browser. Verify login:

sudo runuser -u paperclip -- bash -lc 'codex login status && test -f ~/.codex/auth.json && echo auth-json-present'

Expected success includes:

Logged in using ChatGPT
auth-json-present

Configure a codex_local adapter only after auth succeeds. Use a working directory the runtime user can read and write. Include a timeout appropriate for the task type. If the host blocks sandboxed namespaces, use the approved local trusted bypass setting only after confirming the security tradeoff with the client.

Adapter verification:

curl -sS --max-time 120 -X POST http://127.0.0.1:3100/api/companies/$COMPANY_ID/adapters/codex_local/test-environment \
  -H 'Content-Type: application/json' \
  --data-binary '{"adapterConfig":{"cwd":"/opt/client-workspace","model":"gpt-5.3-codex","modelReasoningEffort":"medium","dangerouslyBypassApprovalsAndSandbox":true,"timeoutSec":900}}'

Expected checks include:

Codex working directory is valid. Codex command is resolvable. Native Codex auth is present. Hello probe passes.

Dashboard access and Hermes + Paperclip connection

Confirm Hermes dashboard or gateway access path. Confirm Paperclip dashboard access path. Prefer Tailscale/private access for ongoing support and avoid public exposure unless explicitly approved. For VPS installs, start SSH port forwarding from the installer machine when dashboards are loopback-only:

ssh -L 9119:127.0.0.1:9119 -L 3100:127.0.0.1:3100 USER@100.x.x.x

Open Hermes dashboard in the local browser. Open Paperclip dashboard in the local browser. Confirm both dashboards are reachable without exposing them publicly. Bookmark or document the approved dashboard URLs. Confirm how Hermes calls Paperclip: local API, private URL, gateway, script, or operator workflow. Confirm Paperclip endpoint or local service address. Confirm shared auth token or internal trust boundary, if any. Confirm timeout behavior and artifact output path. Send a small test job from Hermes to Paperclip. Confirm Paperclip receives the job. Confirm Paperclip creates an artifact or visible task/run. Confirm Hermes can find, summarize, or display the result. Check logs on both services after the test.

SAGE Phase 3

3. Generate

Create the first useful outputs so the install becomes an activated agent team, not just working infrastructure.

Onboarding interview Starter context and operating notes First Paperclip artifact Maintenance notes generated by Hermes Generate completion check

Onboarding interview

Open Hermes from the agreed operator interface. Start a new onboarding session. Paste or run the onboarding interview prompt. Confirm the interview asks about goals, work, tools, communication preferences, constraints, safety boundaries, and success criteria. Answer the interview questions with the client or installer present. Capture any missing context in the session. Ask Hermes to summarize the onboarding interview. Ask Hermes to identify immediate setup gaps. Ask Hermes to identify the first three useful projects. Save the onboarding summary in the agreed project folder or knowledge base.

Onboarding Interview Prompt:

I want you to run a deep onboarding interview with me as my agent.
Your job is to learn enough about me to become genuinely useful: how I think, what I’m building, what matters to me, how I make decisions, how I like to communicate, what I’m responsible for, and what success looks like.
Treat this conversation as foundational context for our future work together. Use it as a reference point whenever a task requires judgment, prioritization, strategy, or alignment with my goals.
Begin by presenting the interview structure in full, organized into categories. Then ask your questions one at a time, in sequence. Be curious, specific, and adaptive. Ask follow-up questions when something is important or unclear. Keep the conversation focused on gathering the context that will help you support me well over the long term.

Starter context and operating notes

Generate a short profile of the user/client. Generate operating preferences. Generate tool access notes. Generate safety boundaries and approval gates. Generate the first project shortlist. Generate a simple handoff note explaining how to use Hermes and Paperclip. Save outputs in the agreed workspace. Confirm generated notes do not contain exposed secrets.

First Paperclip artifact

Choose a low-risk first artifact. Ask Hermes to create the task for Paperclip. Confirm Paperclip receives the task. Generate the artifact. Inspect the artifact. Ask Hermes to revise or improve it if needed. Save the final artifact. Record where it lives. Suggested artifacts: one-page onboarding summary, project plan, checklist, simple webpage draft, client-ready report, troubleshooting runbook, or dashboard guide.

Maintenance notes generated by Hermes

Ask Hermes to summarize how this install is configured. Ask Hermes to list restart, status, and log commands. Ask Hermes to identify unresolved setup risks. Ask Hermes to produce a next-actions list. Save this as the install handoff note. Confirm the maintenance note includes Tailscale IP/private access path and support expectations.

Generate completion check

Onboarding interview has been run or deliberately deferred. User/client context has been summarized. First project shortlist exists. First Paperclip artifact has been generated or explicitly deferred. Install handoff note exists. Output locations are documented.

SAGE Phase 4

4. Evaluate

Verify the install with health checks, restart checks, real project tests, troubleshooting coverage, handoff notes, and internal/client sign-off.

Verification script for final install review

Run a final verification before handoff.

Hermes verification

Version check passes:

hermes --version

Doctor check is clean or known warnings are documented:

hermes doctor

Simple model call works:

hermes chat -q "Say 'Hermes verification passed' and nothing else."

Config path is known:

hermes config path

If gateway is installed, status is healthy:

hermes gateway status

Paperclip verification

Health endpoint works:

curl -sS --max-time 5 http://127.0.0.1:3100/api/health

Companies endpoint works:

curl -sS --max-time 5 http://127.0.0.1:3100/api/companies

Status helper works:

paperclip-status

UI loads at the approved URL. Organization is visible. Agents/projects/issues match the handoff notes. Live runs are empty unless the client intentionally started one. Recent logs show no new startup or adapter errors.

Optional Codex agent verification

Codex auth exists for the runtime user. codex_local test-environment passes. One low-risk test task can produce a harmless planning artifact. No recovery/stalled issues are left unexplained.

Troubleshooting guide

Hermes command not found

Open a new shell. Check whether the install added Hermes to PATH. Run the install script again if the first install was interrupted. Confirm the user is not switching between root and non-root shells unexpectedly.

Hermes cannot call the model

Re-run hermes setup or hermes model. Check provider credentials with hermes auth list or provider-specific setup. Confirm API keys are stored in the Hermes env path, not pasted into config comments. Run hermes doctor. Try a simple hermes chat -q query again.

Hermes gateway is silent

Confirm the gateway process is running. Check ~/.hermes/logs/gateway.log. Confirm the bot token or app credentials are correct. Confirm the bot is invited to the right chat/channel. For Discord, confirm Message Content Intent is enabled. Restart the gateway after config changes.

Paperclip fails with a PostgreSQL/root error

Cause: embedded PostgreSQL cannot run as root.

Stop the failed process. Create or use the paperclip runtime user. Ensure /opt/paperclip is owned by paperclip:paperclip. Re-run install/onboarding/start commands through runuser -u paperclip.

Paperclip health endpoint fails

Confirm the server is running. Confirm port 3100 is not already occupied by another process. Check Paperclip logs. Run paperclip-status if helpers were created. Restart Paperclip cleanly.

Paperclip UI loads but agents do not work

Confirm the agents are not only placeholders. Confirm adapter configuration exists. Confirm runtime user can access the working directory. Confirm Codex auth exists if using codex_local. Run the adapter test endpoint. Check issue comments and heartbeat run logs for errors.

Paperclip creates recovery or stalled issues

Do not delete them blindly. Read the original issue and the recovery issue comments. Check whether the deliverable actually exists. Fix the underlying adapter, permission, or timeout issue. Cancel/hide stale recovery artifacts only after the original work is verified or intentionally abandoned.

Host blocks Codex sandboxing

Check the actual error from the adapter or run log. If the error mentions namespace or bwrap restrictions, confirm whether the host allows unprivileged namespaces. For a trusted local install, discuss the security tradeoff before enabling sandbox bypass. Document the decision in the handoff notes.

Handoff notes template

Complete this before the install session ends.

Client:
Install date:
Installer:

Hermes
- Installed for user:
- Hermes version:
- Config path:
- Env/secrets path:
- Provider/model:
- Enabled toolsets:
- Gateway enabled: yes/no
- Gateway platforms:
- Gateway restart command:
- Known warnings:

Paperclip
- Install path:
- Runtime user:
- Config path:
- Data path:
- UI URL:
- API URL:
- Health endpoint result:
- Start command:
- Stop command:
- Status command:
- Organization/company ID:
- Initial agents:
- Initial projects:
- Adapter type(s):
- Codex auth verified: yes/no/not applicable
- Live runs at handoff:
- Known warnings:

Security and operations
- Who owns credentials:
- Backup plan:
- Approval gates:
- External actions allowed:
- Reporting cadence:
- Escalation contact:

Final verification
- Hermes doctor run: yes/no
- Hermes model test passed: yes/no
- Paperclip health passed: yes/no
- Paperclip UI verified: yes/no
- Paperclip agents verified: yes/no/not applicable

Client sign-off

Ask the client to confirm each item before closing the session.

I can access Hermes from the agreed interface. I understand where Hermes credentials and config live. I can access Paperclip from the agreed URL. I understand how to start, stop, and check Paperclip. I understand which agents are placeholders and which can execute work. I understand the approval gates for outbound or risky actions. I know where install notes are saved. I know who to contact if the system stops responding.

Test project 1 — onboarding pack

Ask Hermes to create an onboarding pack from the interview summary. Have Paperclip generate or track the artifact. Review the artifact for accuracy. Confirm it includes user goals, operating preferences, tools, boundaries, and next actions. Save the final version.

Test project 2 — dashboard walkthrough

Ask Hermes to explain what each dashboard shows. Ask Hermes to identify what healthy status looks like. Ask Hermes to identify what an error looks like. Use Paperclip to create a quick visual or written dashboard guide if useful. Save the guide.

Test project 3 — real work artifact

Choose a real but low-risk business task: project plan, lead research brief, sales/onboarding checklist, simple website/page draft, proposal, report, or troubleshooting runbook. Give Hermes the real task. Confirm Hermes plans the work. Confirm Paperclip generates or tracks the output. Review the artifact. Revise once. Save the result. Record what worked and what failed.

Restart and recovery checks

Stop and restart Hermes or the gateway where applicable. Stop and restart Paperclip. Confirm dashboards recover. Confirm Tailscale/SSH access still works after reconnecting. Confirm port forwarding still works after reconnecting. Confirm logs show the restart. Confirm missing-env or auth errors are understandable. Confirm artifact output path is still correct. Confirm no secrets appear in generated output.