Settings

Paperclip has two settings surfaces, and it matters which one you're looking at.

Profile is your account — your display name and the avatar that shows up next to your comments. Changing it only affects how you appear. Other board users on the same instance have their own profiles and see their own.

Instance settings are the admin controls. They don't live on a separate instance page — you reach them from the same Settings navigation as your organization (tabs like Access, Experimental, Plugins, and Adapters, plus the instance sections on General). Anything you change there applies to the whole Paperclip instance — every company, every user, every agent that runs against this install. If you're running Paperclip on a VPS that hosts five companies, an instance toggle flips for all five.

Company and instance settings now share one navigation. The instance-wide General controls described below live on the organization's own General page (see Company Administration), so instance admins reach them from the same place as the organization settings rather than a separate area.

This guide walks through both, section by section.

Profile

To get here, click your avatar at the bottom of the sidebar to open the account menu, then click your picture and name at the top of the menu. That opens your public profile page; click Edit profile there to land on this page. It's scoped to you — nobody else's profile changes when you edit yours.

Tip: The account menu also has an Invite row when you're allowed to invite people. On a self-hosted instance it opens the Members page on its Invites tab, and it shows for company owners and admins, instance admins, and local boards. On Paperclip Cloud it opens the People settings for your stack instead, and shows only to the stack's owner or admins.

You get three things to work with:

• Avatar — click the round image (or the Upload photo button) to pick a new image from disk. It's uploaded into Paperclip's file storage under the currently selected company's asset space. If no company is selected you can't upload — the page will tell you to select one first. Once an image is set, a Remove button appears next to the upload control.
• Display name — the name shown in the sidebar account footer and as the author on any comments you post. It falls back to "Board" if left blank. The field is capped at 120 characters.
• Email — read-only. Your email is managed by the auth session (the login provider), not by this page. If you need to change it, update it wherever you signed in from.

Click Save profile to persist name or avatar changes. The button is disabled while the name is empty or a save is in flight.

Note: The avatar is stored as an asset under the selected company, but the profile itself is a user-level record. If you switch which company is selected in the sidebar later, your avatar keeps working — it's just that new uploads go to whichever company is active when you upload.

Keyboard shortcuts

Keyboard shortcuts are always on for everyone who's signed in — there's nothing to turn on, here or anywhere else. That covers inbox and task-list navigation plus the global shortcuts: c to create a task, / to search, ? for the shortcuts cheatsheet, and [ and ] to toggle the sidebar and the side panel.

Shortcuts stay out of your way while you type: they ignore key presses inside text fields, and they don't fire while a dialog is open.

Upgrading from an older release? Earlier releases had a Keyboard shortcuts switch — first on the instance General page, then on this Profile page, off by default. Both switches are gone, so after the upgrade shortcuts simply work for every signed-in user.

Instance: General

There's no separate instance General page anymore. Open Settings and you land on General — the first item in the settings sidebar. The top of that page holds your organization's own settings (Organization name, Description, Logo, hiring, and interaction governance). Scroll past Interaction governance and you reach the instance-wide sections described below, sitting just above the Danger Zone. This is where you see how the instance was deployed and flip a few cross-cutting toggles.

Upgrading from an older release? Old links to the instance General or Heartbeats pages still work — they redirect to this General page.

Deployment and auth

Next to the Deployment and auth heading, a small mode badge tells you which deployment profile this instance is running under. The text underneath explains what that means in practice:

• Local trusted — the instance is treating browser requests as a local board operator. No sign-in is required. This is the default when you run Paperclip on your own machine.
• Authenticated public — sign-in is required and the instance is intended to sit on a public URL.
• Authenticated private — sign-in is required, but the instance is intended for a private network (LAN, VPN, or similar).

Three status boxes summarize readiness:

• Auth readiness — whether the auth subsystem is fully configured.
• Bootstrap status — "Setup required" if the initial CEO/board setup hasn't completed yet, otherwise "Ready".
• Bootstrap invite — whether an active first-run invite link is outstanding.

These fields are informational. To change them you change the deployment itself — see Environment Variables.

Censor username in logs

Hides the username segment inside home-directory paths and similar operator-visible log output. Useful if you're sharing screen recordings or pasting transcripts. Off by default. Note that bare username mentions outside of path strings are not masked in the live transcript view — this is a best-effort filter, not a guarantee.

Backup retention

Controls how long automatic database backups are kept at each tier. Paperclip backs up roughly every hour and then thins the backups out over time:

• Daily — every backup is kept for the selected number of days.
• Weekly — one backup per week kept for the selected number of weeks.
• Monthly — one backup per month kept for the selected number of months.

Each tier is a preset picker, so you can only choose from vetted retention windows. Backups are gzipped on disk. Longer retention means more storage — raise the windows only as far as your disk and compliance story require.

AI feedback sharing

Controls whether thumbs-up / thumbs-down votes on AI output can send the voted output to Paperclip Labs. There are two buttons, plus a starting state:

• No default saved yet — the starting state. There's no button for it; the card just tells you the next thumbs up or thumbs down will ask once and then save your answer here.
• Always allow — voted AI outputs are shared automatically.
• Don't allow — voted AI outputs stay local.

The local vote is always saved regardless — this setting only controls whether the content leaves your instance. A Read our terms of service link sits on the same card.

Sign out

A plain Sign out button, the last of the instance sections (just above the Danger Zone). It ends your session and sends you back to the login page. On a local-trusted instance there's usually nothing to sign out of, but the button is still shown unless your operator has hidden it.

Instance: Access

Instance Access is where you promote users to instance admin and pick which companies each user can see. This is different from the roles you grant inside a company.

Instance-level vs. company-level roles

It's worth being explicit about this because the two feel similar:

• A company membership lets a user see and act within one specific company. A user can be a member of several companies, each with its own membership role (operator, manager, etc.). This is set per-company.
• An instance admin can see and manage the instance itself — add/remove instance admins, grant users company access, and open admin-only surfaces. This is set per-user on this page.

A user can be an instance admin without being a member of every company, and a company member without being an instance admin. The two layers are independent.

Finding and inspecting a user

The left pane is a search box and a scrollable user list. Type a name or email to narrow it down. Each row shows:

• The user's name and email
• A green shield icon if they're currently an instance admin
• A count of active company memberships

Click a user to load their detail view on the right.

Promote to instance admin

In the detail view, a button toggles the user's instance-admin status: Promote to instance admin if they're not one, or Remove instance admin if they are. The change takes effect immediately. Be deliberate — instance admins can grant themselves access to any company and can demote other instance admins.

Company access

The lower half of the detail view is a grid of every company on the instance with a checkbox next to each. Tick the ones this user should be a member of, untick the ones they shouldn't, and click Save company access.

Adding access creates an active operator membership by default. If the user needs a higher role inside that company (manager, for example), switch to that company and raise their role there — this page only controls whether they have access, not what role they have.

Beneath the checkbox grid, Current memberships lists what's actually on record, with role, status, and the last update date. Treat this as the source of truth — if it doesn't match what you set in the checkboxes, re-save.

Tip: Running a VPS-hosted instance that hosts multiple companies? Use this page to onboard new people without sharing the database. Create their auth account (through your login provider), find them here, tick the companies they need, and save.

Instance: Adapters

The Adapters page (Settings → Adapters) is the operator view of every adapter currently registered against this Paperclip install. Adapters are how Paperclip talks to an AI runtime — Claude's local CLI, Codex, OpenAI, OpenClaw, and so on — so this is the surface you use when you need to add a new runtime, hide one from agent hiring menus, or upgrade a runtime's package to a newer release.

Alpha: The external adapter system is still under active development. APIs and storage format may change between releases — reach for this page when you need it, but expect the details to keep evolving.

Installed adapters

The page has two sections, stacked top-to-bottom:

• External Adapters — anything you have added yourself, whether from an npm package or a local path. Each row shows the adapter's display label, its registered type, the package name, the version, and how many models the adapter exposes.
• Built-in Adapters — the adapters that ship inside Paperclip itself. They cannot be removed, only hidden. If an external adapter has overridden a built-in (for example, a forked version of the Claude adapter installed from npm), you also see a synthesised "built-in" row tagged Overridden by … so it is obvious which built-in has been shadowed.

A small origin icon sits next to each external adapter: a folder for adapters installed from a local path, and a package icon for adapters installed from npm. Versions appear as a mono-typed v1.2.3 badge.

Health status

The row badges are the fastest way to read adapter health:

• External / Built-in — the source of the adapter.
• v{version} — the currently loaded package version.
• Overrides built-in — this external adapter is replacing a built-in of the same type.
• Hidden from menus / Override paused — the adapter still exists but is not offered when creating or hiring agents. Use this to stage a rollout without uninstalling.

Beneath the label, a subtitle line shows type, the npm package name (when different from the type), and the model count. A zero model count usually means the adapter loaded but could not enumerate models — check the package configuration before enabling it for agents.

Enable / disable

Every row has a power icon on the right-hand side. Clicking it toggles the adapter's visibility without deleting anything:

• For regular adapters (both built-in and plain external), the power button flips the Hidden from menus state. Hidden adapters are kept registered and existing agents on that adapter continue to run, but the adapter is omitted from the adapter dropdown when creating new agents.
• For external adapters that override a built-in, the power button instead pauses or resumes the override. Pausing the override snaps every agent of that type back to the built-in implementation on their next run; resuming restores the external adapter.

Two more icons may appear on external rows:

• Reload (circular arrow) hot-swaps the adapter module in the running process. Useful after you have published a new version of a local-path adapter and want to pick up changes without bouncing Paperclip.
• Reinstall (download arrow) opens a confirmation dialog that checks the npm registry for the latest version, then pulls it and reinstalls the package. Existing agents will use the new version on their next run.

A Remove (trash) icon is available on external adapters only. Removing an adapter unregisters it, tears down its npm install on disk, and cannot be undone — Paperclip prompts for confirmation first.

Per-adapter config

Adapters themselves do not expose configuration on this page — they are packages, not configurable singletons. Each agent picks an adapter and then fills in the fields that adapter requires (working directory, environment variables, credentials). Those per-agent fields live on the agent's Configuration tab, not here.

What this page gives you is the ability to add, upgrade, and retire the adapter packages that populate the agent adapter menu. To install a new external adapter, click Install Adapter in the top-right of the page. A dialog appears with two source modes:

• npm package — enter the package name (for example my-paperclip-adapter) and optionally a version. Paperclip installs the package from npm and registers it.
• Local path — paste a Linux, WSL, or Windows path to a checked-out adapter package. Paperclip auto-converts Windows paths and installs the adapter from disk. Local-path adapters are the fastest way to iterate on a new adapter before publishing.

In both cases the adapter package must export createServerAdapter() — the dialog reminds you of this contract.

For the full catalog of adapters Paperclip supports out of the box, along with the per-agent fields each one expects, see the reference docs: Adapters overview.

Instance: Experimental

Experimental flags opt the instance into features that aren't yet defaults. They're gated here because they may change behaviour, performance, or migrations before they graduate.

What "experimental" means here

An experimental flag in Paperclip is a feature that:

• Has shipped and works,
• Is being evaluated against real usage before it becomes the default, and
• May be renamed, reworked, or promoted to a core setting in a future release.

Turning one on is not dangerous in the "this will break your data" sense — but experimental features come without compatibility guarantees. They may break, change, or be removed at any time, and Paperclip doesn't promise migration or long-term support for them. The page carries a warning to this effect at the top. Flip flags when you have a reason to, not for curiosity; don't lean on an experimental feature for a workflow that has to stay stable, and expect to re-read the release notes if you upgrade.

The available flags

Open Settings → Experimental. The page groups its toggles into up to three sections and lists the cards alphabetically within each one. Where a flag has its own page in the Experimental section (or elsewhere in these docs), the name links to it.

Experimental features — "Optional product features that are still being evaluated."

• Agent Chat — one ongoing conversation per agent. Chat leads the Work group and opens an agent rail beside the nav; agents clarify your goal and hand real work off to tasks.
• Assistant connections (MCP) — connect Codex, Claude, and other assistants to your Paperclip organization so people can review work, delegate tasks, and add feedback. Needs an authenticated instance with a configured public URL.
• Beta skills — lets agents pin beta releases of the Paperclip core skill. Turning it off returns every agent to the default live skill, without removing the pins you saved.
• Built-in Agents — shows Paperclip-managed built-in agent surfaces (built-in roster badges, the Built-in agents tab, and the built-in agent setup controls) and makes the built-in-agent API available. Turn it on before you provision briefs, learning, or reflection-coach; with it off, the built-in-agent routes return 404 Not Found.
• Cases — durable work products (blog posts, tweet storms…) that tasks create and iterate on. Adds the Cases tab and the agent case API. Turning it off hides the tab and blocks the API; existing case data is kept.
• Chat connectors — connect agents to Slack, GitHub, Discord, Microsoft Teams, and Telegram conversations. Turning it off hides chat setup, but existing chat connections keep running.
• Combined Inbox + Task List — folds Inbox into Tasks: one Tasks row carries the unread badge, and a Views menu reaches every inbox and task view.
• Decisions — shows the Decisions item in the main sidebar, the attention home that surfaces the tasks awaiting your input.
• Enable Environments — environment management in company settings, plus project and agent environment assignment (including custom sandbox images).
• Enable External Objects — detects external URLs in issues and shows live status for referenced pull requests, tickets, and other work objects.
• Enable Isolated Workspaces — execution-workspace controls in project configuration and isolated (git-worktree) checkouts for task runs. If you're not using isolated workspaces, leave this off. Once it's on, a Use Isolated Workspaces By Default card appears at the bottom of this section.
• Experimental File Viewer — task-detail controls for browsing and previewing workspace files.
• First task: propose with a plan document — when someone's first request is a single task, the chief of staff writes a short plan document and a checkbox card instead of a one-card confirmation. Applies to organizations created after you flip it.
• Memory connectors — exposes Mem0, Zep, Supermemory, Cognee, and Honcho setup. Hiding setup does not stop saved connections.
• Paperclip Runner — lets new Codex agents select the experimental Rust Paperclip Runner. On by default on self-hosted instances and off by default on Cloud unless managed configuration changes it. Turning it off hides the choice without affecting existing native runs.
• Simplified English Interactions — tells agents to write confirmations, questions, suggested tasks, and checkbox prompts in ASD-STE100 Simplified Technical English, with brief context on what each decision needs.
• Status Cards — the shared status-card board and its gated API. Enabling Status Cards also enables Summaries.
• Streamlined UI — on by default. The simplified main sidebar, shared Tasks and Inbox presentation, focused task detail layout, and contextual navigation across Agents, Routines, Skills, and Settings. Turning it off restores the legacy shell and navigation; task and page data are unchanged.
• Summaries — Summarizer-generated status slots on project and workspace pages, with on-demand refresh and revision history. Status Cards requires Summaries, so disabling Summaries also disables Status Cards.

Paperclip Developer Mode — "Internal tools for developing, testing, and debugging Paperclip." You won't need these for day-to-day use.

• Auto-Restart Dev Server When Idle — only relevant under pnpm dev:once; restarts a stale dev boot once all local agent runs finish.
• Managed Environment Only — hides the local environment and runs all agents in the platform-managed environment.
• Paperclip Developer Mode — shows internal maintainer tools and observability links, including Honeycomb trace queries on run pages.
• Run tasks in this worktree — only appears when the server is running inside a git worktree.
• Server Info Debug View — a "Server" section in the account drawer with the server restart time and running commit.
• Smoke Lab — adds a Smoke Lab tab under Apps → Developer and an Integration smoke card on the dashboard for exercising integration paths against local fixtures. Private (non-public) deployments only.
• Task Plan Decomposition — accepted-plan decomposition history on task detail pages, for debugging sub-task creation.

Legacy — "These features are going to be removed."

• Classic Task Interface — restores the previous task detail page: the page-level header, the plain comment thread, and the fixed Properties sidebar.
• Goals Sidebar Link — restores the Goals item in the main sidebar while the goals surface is being evaluated.

No longer on this page

If you're coming from an older release, a few toggles you may remember are gone:

• Task Watchdogs — no flag any more. Watchdog controls are always available on tasks.
• Auto-Create Recovery Tasks — retired, along with its preview and run actions.
• Cloud Sync — retired, toggle included. To move a company between instances, use company Import/Export.
• Streamlined Left Navigation Bar — replaced by Streamlined UI.

Toggles take effect immediately on save. If one misbehaves, flip it back off — no migration is required.

Operator controls for hosted deployments

If you run Paperclip for other people — a managed cloud, an internal shared server — you can shape which settings surfaces your users see and what the defaults are, without touching any user's data. Two environment variables do this. Both are read at boot, applied at read time, and never persisted: clear the variable and stock behavior comes back everywhere a user hasn't chosen otherwise. With both unset, the UI and API behave exactly as this page describes.

Hide surfaces with PAPERCLIP_HIDDEN_SETTINGS

Set PAPERCLIP_HIDDEN_SETTINGS to a comma-separated list of surface keys to remove from the UI. Some keys also floor their mutation API with a 403 (carrying the settings_operator_managed code); the rest hide UI only, so agents and integrations keep working against the underlying routes.

The keys you can list:

• Instance pages — instance.profile, instance.environments, instance.access, instance.experimental, instance.plugins, instance.adapters. (The Instance General page is the settings root and can't be hidden; hide its sections individually instead.)
• Company pages — company.members, company.invites, company.secrets, company.export, company.import. Hiding company.import also floors the import API; the other company keys are UI-only.
• Company sub-tabs — company.secrets.vaults, company.secrets.proposals (hide one tab while the Secrets page stays up).
• Instance General sections — instance.general.deploymentStatus, instance.general.censorUsernameInLogs, instance.general.backupRetention, instance.general.feedbackDataSharingPreference, instance.general.signOut. Field-backed sections also floor writes to that field; deploymentStatus and signOut are read-only UI. The old instance.general.keyboardShortcuts key no longer exists — keyboard shortcuts are always on — so if it's still in your list, Paperclip ignores it and logs a warning.
• Experimental flags — instance.experimental.<flagKey> for any individual flag, or hide the whole page with instance.experimental.
• Every experimental flag, now and later — instance.experimental.*. The wildcard hides every toggle in the server's own feature catalog, so toggles added by a future upgrade arrive hidden too, with no change to your environment. The Experimental page itself stays reachable. To keep a few toggles available, add exceptions prefixed with !, such as !instance.experimental.enableEnvironments.

For example, this leaves only the Environments toggle on the Experimental page and hides the Plugins page:

PAPERCLIP_HIDDEN_SETTINGS='instance.plugins,instance.experimental.*,!instance.experimental.enableEnvironments'

Exceptions only loosen the wildcard. If you also list a toggle explicitly, or hide the whole instance.experimental page, that wins no matter what order the entries are in — and an exception without the wildcard does nothing. Hiding a toggle never changes its value: the setting keeps whatever it was set to, and the settings API still lets you read it, but trying to change it returns 403 with settings_operator_managed. Images that predate wildcard support ignore the wildcard and its exceptions, so during a rolling upgrade keep any explicit per-toggle entries until every image is on the newer release.

Unknown keys are warned about and ignored rather than rejected, so you can roll one list across a fleet of mixed app versions — an image that predates a key simply keeps that surface visible instead of refusing to boot.

Override defaults with PAPERCLIP_SETTING_DEFAULTS

Set PAPERCLIP_SETTING_DEFAULTS to a JSON object to replace the schema default of selected Instance General settings — currently feedbackDataSharingPreference. For example:

PAPERCLIP_SETTING_DEFAULTS='{"feedbackDataSharingPreference":"allowed"}'

Your value substitutes for the schema default at read time: any field still sitting at its default resolves to yours, while a user's explicit non-default choice always wins. Parsing is fail-closed — malformed JSON or an invalid value for a known field stops the server from booting, because a silently dropped policy default is worse than a loud failure. Unknown field names are warned about and ignored.

The two controls are orthogonal: pair them when you want a default and want the control hidden.

Where to go next

• Heartbeats & Routines — the full picture of timer vs. event-driven wakes, and how to configure individual agents.
• Environment Variables — the deployment-level settings that the General page reports on (auth mode, bootstrap state, exposure).