Coordinate multiple AI agents with Paperclip

Olares version: 1.12.7+▾

Olares 1.12.7+Olares 1.12.6

Paperclip is an open-source platform for coordinating multiple AI agents under one unified workspace. By setting up a virtual company, you add AI agents powered by Claude Code, Codex, OpenCode, Cursor, or other providers, and assign them issues to work on. Whether the task involves coding, research, or content creation, Paperclip manages the workflow.

Running Paperclip as a self-hosted app on Olares ensures that your API keys, task history, and agent outputs remain entirely private on your device.

Prerequisites

Before you begin, you need:

• An Olares device running Olares 1.12.7 or later, with sufficient disk space and memory.
• Access to Router for local model connections.
• Qwen3.8-27B (llama.cpp) installed from Market, if you plan to use a local model.

Optional: Use a different model

Install another chat model from Market, or create a model instance with Engine Base apps. Then select it as the default chat model on Router's Default models page. Clients configured with default-chat use the new default without changing their model settings.

To keep a client on one specific model, use the full model name from Router's How to call this model window instead.

Learning objectives

In this guide, you will learn how to:

• Install Paperclip on Olares.
• Configure API keys for the agents you plan to use.
• Set up the initial admin user account.
• Set up your first company, agent, and task.
• Create an issue and track agent progress.
• Monitor operations and metrics from the dashboard.
• Optional: Use local models with Paperclip.

Install Paperclip

1. Open Market and search for "Paperclip".

   

2. Click Get, then click Install. When the installation finishes, two shortcuts appear in the Launchpad:

   

Initialize Paperclip

After installing Paperclip, create the first admin account to complete the initial setup. If you plan to use cloud models, configure your API keys first.

Configure API keys

If you plan to use OpenAI, Anthropic (Claude), Google Gemini, or Cursor, you can configure the corresponding API keys in advance as environment variables in the Settings app.

TIP

Before creating an admin account, set up your API key in Settings so cloud models can be used immediately.

1. Open Settings, then go to Applications > Paperclip > Manage environment variables.

   

2. Click edit_square next to a variable, enter your API key in the Value field, then click Confirm.

   Paperclip supports the following variables:

   Variable	Used by
   ANTHROPIC_API_KEY	Claude Code, OpenCode, Pi
   OPENAI_API_KEY	Codex, OpenCode, Pi
   GEMINI_API_KEY	Gemini CLI, Cursor
   CURSOR_API_KEY	Cursor

3. Click Apply to save and apply the new keys.

Add more API keys later

Return to this section to add or update keys at any time. Repeat this procedure and restart Paperclip to apply new configurations.

Create an admin account

Paperclip ships without a default user account. To access the platform for the first time, you need to create an admin account through the registration flow.

1. Open Paperclip from the Launchpad, and click Create account.

2. On the sign-up page, fill in the required information and submit.

3. After sign-up, click Claim this instance to bind the admin account.

   

4. Enter your company name and complete the onboarding process as prompted.

Complete onboarding

When you create your first organization, Paperclip opens onboarding to help you set up the organization and its first agent.

1. Enter the organization name and follow the prompts to describe its goal.
2. Name your first agent.
3. Select a model provider. The default onboarding currently supports only OpenAI and Claude. Follow the prompts to connect the corresponding account or provide an API key, select a model, and verify the connection.
4. Complete the guided agent setup to enter your organization's workspace.

Create your first agent with another adapter

To use another adapter, such as OpenCode or Hermes, first create the organization. Then manually enter this URL in your browser's address bar:

https://<your-paperclip-domain>/agents/all

From the agent list, click the button to create an agent, enter its name, select an adapter, and complete its runtime configuration.

The OpenCode agent creation form currently supports only OpenRouter connections. To use a local model, follow Use local models in Paperclip to create an agent without an AI connection binding through the CLI.

Create and track issues

In Paperclip, all work happens through issues. When you create an issue, Paperclip assigns it to an existing agent. If no suitable agent exists for the specific request, Paperclip automatically "hires" a new one to complete the job.

1. On the Issues page, click New issue in the left sidebar.

2. Specify details for the issue. For example:

   • Issue title: Write a guide on AI servers.
   • Description: Hire a writing agent to research and draft a 200-word article explaining the benefits of self-hosting AI models.
   • Assignee: Select CEO to evaluate the requirements.

   

3. Click Create Issue. Paperclip assigns the issue and the agent starts working.

4. Click Inbox in the left sidebar to monitor incoming requests and execution progress. If the assigned agent decides to delegate the task, a hiring request appears in your inbox.

   

5. Go to the Agents section in the left sidebar to see the newly hired writer agent and its details.

   

6. Review the agent's output:

   a. Go to the Issues page, then select the issue to view its details. Look for the output directly in the chat history.

   

   b. If the output is missing from the chat, enter a comment in the issue asking the agent for the file path. Open the Olares Files app, then go to the specified directory to retrieve your document.

   

Monitor operations from the dashboard

As your agents complete issues, use the dashboard to track your company's overall performance, monitor API costs, and identify potential bottlenecks.

1. Click Dashboard in the left sidebar.

   

2. Review the top agent cards to see the most recent tasks your agents worked on and their execution duration.

3. Check the high-level metrics to monitor operational health, such as the total API cost incurred for the current month.

4. Analyze the 14-day trend charts to spot performance changes:

   • Run Activity: Check the total number of agent executions.
   • Issues by Priority: View active issues grouped by urgency (critical, high, medium, and low).
   • Issues by Status: Track progress by reviewing which issues are in progress, completed, or blocked.
   • Success Rate: Monitor the execution success rate of your AI workforce.

5. Scroll to the activity log to audit recent system events and agent behaviors. This log provides a chronological trail of all recent tasks.

Use local models in Paperclip

Use local models with caution

Paperclip is a fully autonomous multi-agent collaboration platform. Running it entirely on local models can cause workflow disruptions due to model capability limits, context overflow, or concurrency restrictions, potentially leading to cascading failures.

Consider using a hybrid configuration: assign high-performance cloud models to critical roles such as CEO or CTO, while using local models for execution-focused agents to reduce costs. Alternatively, designate local models as cheap model for less demanding tasks.

Carefully assess the capabilities of each model and your workflow requirements to determine the optimal setup.

Editing opencode.json alone does not configure OpenRouter-bound agents

In the latest version of Paperclip, the agent creation form connects OpenCode to OpenRouter by default, rather than using the local-model configuration from your existing OpenCode configuration file. When running an agent bound to an OpenRouter AI connection, Paperclip uses an isolated configuration directory, injects OpenRouter credentials, and explicitly passes the agent’s selected model, overriding the default model in your configuration file. Simply editing opencode.json or opencode.jsonc is no longer sufficient for configuring these agents.

OpenCode can call an OpenAI-compatible local model through Olares Router. This OpenCode runs inside Paperclip and is separate from the OpenCode app in Market.

Prepare the local model

Install and start Qwen3.8-27B (llama.cpp) from Market, then get its connection details from Router.

How model connections work

On Olares 1.12.7 and later, AI clients connect through Olares Router. Router provides the Base URL and routes default-chat to the model selected on its Default models page.

This guide uses Qwen3.8-27B (llama.cpp) as the default chat model. For connection formats and API key requirements, see Connect AI apps.

1. Open Router from Launchpad. On Default models, set Qwen3.8-27B (llama.cpp) as the default chat model.

2. Go to LLM, find Qwen3.8-27B (llama.cpp), and click View connection example on its row.

3. In How to call this model, select Apps in Olares and copy the Base URL, including /v1.

4. For the model name, use default-chat.

   Selecting a model in your app

   default-chat is a routing name and does not appear in model lists loaded from Router. If the app you are connecting to Router loads a model list, add default-chat manually. If the app only supports selecting a listed model, select the full model name shown in Router's How to call this model window.

5. For the API key, leave the field empty. If the app you are connecting to Router requires a value, enter olares.

Configure OpenCode

The persistent config path inside Paperclip is /paperclip/.config/opencode/opencode.json.

• If opencode.json exists, merge the fields below into it, preserving other providers, plugins, MCP servers, and settings.
• If only opencode.jsonc exists, back it up and convert a copy to strict JSON, removing comments and trailing commas. Preserve its settings. After conversion, move the original JSONC outside the active config directory so two active files do not conflict.
• If neither exists, create opencode.json.

Use this example for Router's default model. Replace the example baseURL with the API Base URL copied from Router, including /v1. Do not use the model application's web page URL.

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false,
  "model": "olares/default-chat",
  "small_model": "olares/default-chat",
  "provider": {
    "olares": {
      "name": "Olares local model",
      "npm": "@ai-sdk/openai-compatible",
      "models": {
        "default-chat": {
          "name": "Local model via Router"
        }
      },
      "options": {
        "baseURL": "https://router.your_olares_id.olares.com/v1"
      }
    }
  }
}

Follow the Router connection instructions for authentication. If your endpoint requires a key, configure that endpoint's key; an OpenAI or OpenRouter cloud key is not a substitute. Do not publish credential files in support requests.

Create an unbound OpenCode agent

1. Register and obtain instance-admin or organization access, then create an organization. You do not need a cloud-model key to configure OpenCode itself.
2. Use your own administrator account with the bundled Paperclip CLI to create an agent without runtimeConfig.aiConnection.
3. Open Paperclip CLI from Launchpad. In the command below, replace https://your-paperclip-domain with your Paperclip application URL, without /api or a dashboard path:

export PAPERCLIP_LOCAL_API='https://your-paperclip-domain'
paperclipai auth login --api-base "$PAPERCLIP_LOCAL_API" --no-browser

Open the approval URL printed by the CLI in your browser and approve access using your own Paperclip account. This authenticates the CLI to Paperclip, not to a model provider. Then list organizations:

paperclipai company list --api-base "$PAPERCLIP_LOCAL_API" --json

Copy the intended organization's UUID from id, not its short prefix, and create one agent:

export PAPERCLIP_LOCAL_COMPANY='<organization-uuid>'
mkdir -p /paperclip/workspaces/local-model
paperclipai agent create \
  --api-base "$PAPERCLIP_LOCAL_API" \
  --company-id "$PAPERCLIP_LOCAL_COMPANY" \
  --payload-json '{
    "name": "Local model agent",
    "role": "general",
    "adapterType": "opencode_local",
    "adapterConfig": {
      "cwd": "/paperclip/workspaces/local-model",
      "model": "olares/default-chat"
    },
    "runtimeConfig": {
      "heartbeat": {
        "enabled": false,
        "maxConcurrentRuns": 1
      }
    },
    "permissions": {
      "canCreateAgents": false
    }
  }' --json

Keep the returned agent ID. This creates a new agent; rerunning the command creates another one. The disabled periodic heartbeat and hiring permission keep the initial validation controlled. maxConcurrentRuns: 1 applies only to this agent, not to all agents or all clients of the model.

Verify the saved configuration:

paperclipai agent get '<agent-id>' --api-base "$PAPERCLIP_LOCAL_API" --json

Confirm adapterType is opencode_local, adapterConfig.model is olares/default-chat, and runtimeConfig.aiConnection is absent. Open Agents in Paperclip and select this agent.

Configure an existing agent

For an agent retained after an upgrade, first check whether runtimeConfig.aiConnection is absent. If it is, merge the configuration above and set the agent’s model to olares/default-chat, preserving its other settings. If the agent already has an OpenRouter binding, create an unbound agent using the CLI procedure above instead.

In Paperclip CLI, authenticate with paperclipai auth login as described above and merge the OpenCode configuration before updating the agent. Wait for active runs to finish. Replace the URL and <agent-id> below with your Paperclip application URL and the existing agent's ID. The bundled image includes jq.

(
  set -eu
  umask 077
  PAPERCLIP_LOCAL_API='https://your-paperclip-domain'
  PAPERCLIP_LOCAL_AGENT='<agent-id>'
  PAPERCLIP_CONFIG_BACKUP=$(mktemp -d /paperclip/agent-config-backup.XXXXXX)

  paperclipai agent get "$PAPERCLIP_LOCAL_AGENT" \
    --api-base "$PAPERCLIP_LOCAL_API" --json \
    > "$PAPERCLIP_CONFIG_BACKUP/agent-before.json"

  if ! jq -e '
    .adapterType == "opencode_local" and
    .runtimeConfig.aiConnection == null
  ' "$PAPERCLIP_CONFIG_BACKUP/agent-before.json" > /dev/null; then
    echo 'Stop: this is not an unbound OpenCode agent.' >&2
    exit 1
  fi

  jq '{
    adapterConfig: ((.adapterConfig // {}) + {model: "olares/default-chat"})
  }' "$PAPERCLIP_CONFIG_BACKUP/agent-before.json" \
    > "$PAPERCLIP_CONFIG_BACKUP/update.json"

  paperclipai agent update "$PAPERCLIP_LOCAL_AGENT" \
    --api-base "$PAPERCLIP_LOCAL_API" \
    --payload-json "$(cat "$PAPERCLIP_CONFIG_BACKUP/update.json")" --json \
    > "$PAPERCLIP_CONFIG_BACKUP/agent-after.json"

  jq -e '
    .adapterType == "opencode_local" and
    .adapterConfig.model == "olares/default-chat" and
    .runtimeConfig.aiConnection == null
  ' "$PAPERCLIP_CONFIG_BACKUP/agent-after.json"

  printf 'Configuration backup: %s\n' "$PAPERCLIP_CONFIG_BACKUP"
)

This command backs up the agent configuration and stops if the agent is not an unbound OpenCode agent. It changes only adapterConfig.model, preserving the other adapter settings and leaving runtimeConfig unchanged. Do not edit this agent's configuration elsewhere while the command runs. A final true confirms the saved model and absence of an AI connection binding; it does not verify model inference.

Keep the backup directory private because the configuration may contain credentials. Then open the agent in Agents and run its connection test before assigning work.

Use Market to restart Paperclip after changing shared configuration, once active work has stopped. Do not modify /app, replace the container image manually, or edit the database to detach a connection.

FAQs

Which agent adapters does Paperclip support?

Paperclip currently supports the following agent adapters. You configure specific API keys as environment variables depending on the adapter you choose:

• Claude Code: Requires ANTHROPIC_API_KEY.
• Codex: Requires OPENAI_API_KEY.
• OpenCode: Authentication depends on the model provider. Local models may not require an API key. To use OpenRouter, enter an OpenRouter API key in the Paperclip interface.
• Pi: Requires ANTHROPIC_API_KEY or OPENAI_API_KEY.
• Cursor: Requires CURSOR_API_KEY.

Can I use Hermes Agent as an agent runtime?

Yes, but it is not recommended for production environments. Note the following:

1. This Hermes Agent runs inside the Paperclip container and is separate from the Hermes Agent app installed from the Olares Market. You need to install and configure it separately in the Paperclip CLI (pip install hermes-agent).

2. The Hermes Agent and Paperclip adapter are still in development. Connection stability issues might require significant debugging.

3. Ensure the following configurations are correct, otherwise the agent might fail to work:

   • Turn off the manual approval setting to prevent Paperclip from timing out while waiting for approval when calling the agent:

   hermes config set approvals.mode "off"
   hermes config set approvals.cron_mode "approve"

   • Ensure your Hermes Agent has PAPERCLIP_API_KEY set and the Paperclip Skills installed so it can fetch and modify tasks in Paperclip.

Codex adapter fails to authenticate

After you update OPENAI_API_KEY and restart Paperclip, the Codex adapter might still fail to authenticate. This happens because the codex login command attempts to open a local browser for OAuth, which the background container cannot do.

To resolve this issue, run a manual device-auth login:

1. Open Control Hub, then go to Browse > paperclip-{username} > Deployments > paperclip.

2. Under Pods, click the pod name to view its containers, then click terminal next to the paperclip container to open the pod terminal.

   

3. Type the following command, then press Enter:

   codex login --device-auth

4. Open the device-auth link in your browser and sign in to complete the authorization. Then retry the Codex adapter in Paperclip.

   

Learn more

• Paperclip documentation: Official docs for concepts, features, and configuration.
• Orchestrate multi-agent workflows with oh-my-openagent: Run multi-agent collaboration inside a single OpenCode instance on Olares.
• Set up OpenCode as your AI coding agent: Install and configure OpenCode, a common Paperclip adapter.