paperclip-ensure-oss-120b-assistant

name	paperclip-ensure-oss-120b-assistant
title	Ensure OSS‑120B Assistant Agent appears in Paperclip dashboard
description	Verify and, if needed, create the oss-120b-assistant agent in Paperclip after server startup, ensuring it is visible in the agents dashboard.
author	Hermes Agent

When to Use

Verify and, if needed, create the oss-120b-assistant agent in Paperclip after server startup, ensuring it is visible in the agents dashboard.

Overview

This skill contains a reusable operational workflow. Follow the existing task-specific steps and examples in the sections below.

Prerequisites

• Paperclip server running (UI accessible).
• Environment variables set for the OpenAI‑compatible backend:

  export OPENAI_API_BASE="http://141.33.165.84:8000/v1"
  export OPENAI_API_KEY=""
  export OPENAI_MODEL="oss-120b"
  

• npx paperclipai CLI installed (comes with the Paperclip installation).

Steps

1. Check existing agents via CLI

   npx paperclipai agent list --json
   

   Look for an entry with name: oss-120b-assistant (or similar).

2. If the agent is missing, create it via the Paperclip UI or authenticated API

   The current CLI exposes agent list and agent get, but not agent create. So use the UI (Agents → New Agent) or an authenticated POST to /api/companies/:companyId/agents.

   When creating the agent, use:

   • name: oss-120b-assistant
   • adapter type: hermes_local
   • model / adapter config targeting oss-120b

   hermes_local tells Paperclip to use the local/OpenAI-compatible endpoint.

3. Verify the agent exists

   npx paperclipai agent list --json
   

   or, if you know the UUID:

   npx paperclipai agent get <agent-id>
   

4. Refresh the UI

   • Open the Paperclip dashboard (http://<public-ip>:3100).
   • Navigate to Agents. The oss-120b-assistant entry should now be listed.

5. Optional: Automate verification on server start Add a lightweight verification step to a startup script (e.g., ~/.paperclip/startup.sh) and call it after the server launches:

   #!/usr/bin/env bash
   export OPENAI_API_BASE="http://141.33.165.84:8000/v1"
   export OPENAI_API_KEY=""
   export OPENAI_MODEL="oss-120b"
   
   # Start Paperclip in background
   npx paperclipai run &
   sleep 5   # give the server a moment to start
   # Verify the agent exists
   npx paperclipai agent list --json
   

   Make the script executable (chmod +x ~/.paperclip/startup.sh) and run it instead of the raw npx paperclipai run command.

Pitfalls & Tips

• Configuration mismatch: The server must be in deploymentMode: "authenticated" (or another mode that allows custom bind) for the CLI to talk to it.
• Port confusion: UI runs on the public port (3100 or 3101 depending on your bind) while the API listens on the same configured Paperclip server port. The CLI contacts the API via the publicBaseUrl defined in ~/.paperclip/instances/default/config.json.
• Missing environment variables: If OPENAI_API_BASE is not exported, the agent or server-side model routing will fall back to defaults and fail against the intended local backend.
• Heartbeat smoke tests: In current hermes_local builds, a wakeup run can appear to start correctly but still fail or stall if the heartbeat prompt uses raw Paperclip API calls without authentication. If you see repeated 401s against /issues or /agents/me, inject a Paperclip agent API key into adapterConfig.env (for example as PAPERCLIP_API_KEY) and use an authenticated smoke-test prompt/template for verification instead of the default unauthenticated heartbeat snippet.

Verification

• After following the steps, the agents dashboard should display a row:

  Name	Provider	Model	Adapter
  oss-120b-assistant	openai	oss-120b	hermes_local

• Running a quick test via the UI (e.g., a chat with the new agent) should return responses generated by the local OSS‑120B model.
• For heartbeat-based verification, a successful smoke test should prove three things: the run is accepted by /api/agents/:id/wakeup, the Hermes subprocess starts with model=oss-120b, and authenticated Paperclip API reads (such as agent identity or issue listing) return 200 rather than 401 from inside the agent run.
• If a wakeup run hangs while polling CLI auth or logs repeated unauthorized issue reads, treat that as an integration bug in the heartbeat prompt/auth path rather than as an OSS‑120B inference failure.

---

Created by the Hermes agent to streamline Paperclip agent management.