Hermes + Paperclip Client Installation Checklist

Section 1

1. Installation goal

By the end of the session, the client should have:

Hermes Agent installed and able to run from the terminal. A working model/provider configured for Hermes. Required Hermes tools enabled for the client’s operating channels. Optional messaging gateway connected if the client wants Telegram, Discord, Slack, email, or another chat interface. Paperclip installed on a stable Linux host or VPS. Paperclip running under a non-root runtime user. Paperclip available at a verified local or private URL. A first Paperclip company/organization created. At least one safe agent or placeholder agent configured. Health checks, logs, restart commands, and handoff notes documented.

Section 2

2. Pre-install decisions

Confirm these decisions before touching the server.

Choose the install environment: Client laptop or workstation for local testing. Dedicated VPS for always-on operation. Private network host reachable over Tailscale, WireGuard, VPN, or SSH. Choose the primary operator path: Hermes CLI only. Hermes CLI plus messaging gateway. Hermes as an operator for a Paperclip organization. Choose the preferred model/provider for Hermes: OpenRouter API key. Anthropic API key. OpenAI/Codex OAuth. Nous Portal OAuth. Other supported provider. Choose whether Paperclip agents will be: Placeholder/process agents for planning and visualization only. Codex-backed local agents for real work. Another adapter type approved by the client. Choose exposure level for Paperclip: Loopback-only local trusted mode. Private network access only. Public HTTPS behind reverse proxy, authentication, and access controls. Identify who will own credentials after handoff.

Section 3

3. 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.

Section 4

4. Target machine requirements

Use a modern Linux host for the smoothest install.

Ubuntu 22.04/24.04, Debian, or equivalent Linux host available. CPU and memory appropriate for a Node/Python agent stack. Minimum for testing: 2 CPU cores and 4 GB RAM. Recommended for always-on use: 4+ CPU cores and 8+ GB RAM. At least 20 GB free disk space for dependencies, logs, sessions, and Paperclip data. Outbound HTTPS access to GitHub, package registries, and model providers. Python 3.10+ available. Node.js available or installable. npm/corepack/pnpm available or installable. Git installed. curl installed. systemd or another service supervisor available for long-running services. Time synchronization enabled. Firewall rules understood before exposing any service.

Section 5

5. 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.

Section 6

6. 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.

Section 7

7. 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.

Section 8

8. 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.

Section 9

9. 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.

Section 10

10. 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.

Section 11

11. 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

Section 12

12. 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.

Section 13

13. 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'

Log in as the Paperclip runtime user:

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.

Section 14

14. Hermes + Paperclip operating configuration

Configure the system so the client knows who is responsible for what.

Define Hermes’ role: CLI assistant only. Messaging assistant. CEO/operator coordinating Paperclip work. Define Paperclip’s role: Visual company operating system. Work queue for agents. Execution environment for Codex-backed staff. Define approval gates: No emails without approval. No DMs without approval. No purchases without approval. No production deploys without approval unless explicitly authorized. No customer-facing promises without review. Define reporting cadence: Daily summary. Weekly review. Alert-only. Client-triggered only. Define where work artifacts are saved. Define where logs and handoff notes are saved.

Section 15

15. 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.

Section 16

16. 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.

Section 17

17. 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

Section 18

18. 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.

Section 19

19. Minimum acceptance checklist

The installation is not complete until these are true:

Hermes hermes --version works. Hermes can complete a simple model call. Hermes hermes doctor has no unexplained critical failures. Paperclip runs under a non-root user. Paperclip /api/health returns healthy status. Paperclip UI is reachable from the approved access path. At least one Paperclip organization exists. Agent execution status is clear: placeholder, Codex-backed, or other. If Codex-backed agents are enabled, adapter verification passes. Start/stop/status commands are documented. Credentials ownership and approval gates are documented. Handoff notes are complete.