mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 16:29:42 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Paperclip Runner runs Claude and Codex agents from one shared provider pack. The pack pins an exact Claude Agent SDK (which bundles Claude Code) and an exact Codex CLI. > - #22222 added Claude Fable 5.2 (minimum Claude Code 2.1.321) and GPT-6.2 Sol and Astra (minimum Codex 0.169.1). The pack still bundles Claude Code 2.1.286 and Codex 0.160.0. > - Because of this, Paperclip Runner stops these models with a named version error, and native remote Codex accepts only `>=0.149.0 <0.161.0`. > - This pull request moves the provider pack to Agent SDK 0.3.328 (Claude Code 2.1.328) and Codex 0.170.0. It moves every constant that depends on these pins, and the remote Codex window to `<0.171.0`. > - The benefit is that Fable 5.2 and GPT-6.2 run on Paperclip Runner after a sandbox image with this pack is promoted. ## Linked Issues or Issue Description Refs #22222 (adds the models and the version floors; this pull request makes them runnable on Paperclip Runner). Refs #18488 (moves only the Codex pin to 0.166.0 and the window to `<0.167.0`; it is not updated since November 1 and has conflicts with `master`). Refs #18486 (GPT-6.1 Terra needs Codex 0.165.0; Codex 0.170.0 satisfies it). **Overlap with #18488.** #18488 changes the same Codex pin locations. This pull request uses a newer pin (0.170.0) and also moves the Claude runtime. If this pull request merges first, #18488 has no remaining change. I did not change the #18488 branch. ## What Changed - Claude runtime: `@anthropic-ai/claude-agent-sdk` 0.3.286 → 0.3.328 (Claude Code 2.1.286 → 2.1.328). This changes the root `pnpm.overrides`, `pnpm-workspace.yaml`, the ACPX `claude` profile, and the qualified Claude runtime in `installation-integrity.ts`, with new executable digests for Linux x64, Linux ARM64, macOS ARM64, and macOS x64. - Codex runtime: `@openai/codex` 0.160.0 → 0.170.0. This changes the runner dependency, the `codex-acp@1.6.2>@openai/codex` override, the `codex-acp` patch dependency line, the ACPX `codex` profile, and the qualified Linux x64 runtime with its new executable digest. - The ACP bridges do not change: `claude-agent-acp` 0.73.0 and the patched `codex-acp` 1.6.2. Their `commandDigest` values and profile versions do not change. - Generated declarations: `generated-profiles.ts` and `generated_acpx_profiles.rs` are regenerated with `generate:acpx-profiles`. - Remote native Codex window: `REMOTE_CODEX_MAXIMUM_VERSION_EXCLUSIVE` 0.161.0 → 0.171.0. The minimum stays at 0.149.0. Images with Codex 0.149.0 through 0.170.x are accepted. - Codex company observability: the qualified-version check moves to `codex-cli 0.170.0`. The `otel` configuration keys that Paperclip writes (`exporter`, `trace_exporter`, `metrics_exporter`) are present in the 0.170.0 configuration schema. The `OtelExporterKind`, `OtelHttpProtocol`, and `OtelTlsConfig` definitions are identical to 0.160.0. - Daytona runner image probes (`Dockerfile`, `Dockerfile.release`) expect `codex-cli 0.170.0` and `2.1.328 (Claude Code)`. The remote npm install spec in `server/src/adapters/registry.ts` is `@openai/codex@0.170.0`. - Tests: fixtures and assertions that mirror the pins use the new versions. The window tests accept 0.161.0 through 0.170.99 and reject 0.171.0. The ACPX gate tests now show that Fable 5.2 and GPT-6.2 are admitted. A new test mocks an older bundled runtime and keeps the named version-gap errors covered. The fallback test shows that GPT-6.2 stays on 0.170.0 and still falls back on 0.160.0. - Opt-in qualification scripts (`scripts/tests/native-cleanup-paginated-codex.mjs`, `native-provider-startup-codex.mjs`) require Codex 0.170.0. - Documentation: `docker/daytona-runner/README.md`, `doc/architecture/paperclip-runner-compatibility.md`, `doc/agent-observability.md`, `docs/deploy/environment-variables.md`, and the deferred item in `doc/adapter-model-audit-2026-11-18.md`. - `pnpm-lock.yaml` is not part of this pull request. The refresh bot regenerates it on `master`, as for the previous pin refreshes (#14942, #14993). ## Verification Sources, checked on 2026-11-19: - npm registry: `@openai/codex@0.170.0` (published 2026-11-18T03:45Z) and `@anthropic-ai/claude-agent-sdk@0.3.328` (published 2026-11-18T23:13Z, `claudeCodeVersion` 2.1.328). Both are the `latest` tags. - [Codex releases](https://github.com/openai/codex/releases) 0.161.0 through 0.170.0. The notes record no app-server protocol break. 0.169.0 keeps project configuration disabled for `codex exec` in untrusted directories; Paperclip's CLI path already uses `--skip-git-repo-check`, and the native path uses `app-server`. - [Claude Code changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) 2.1.287 through 2.1.328. See "Risks" for the headless changes that I reviewed. Digests and package shape: - I downloaded each platform archive with `npm pack`, which verifies registry integrity, and computed the SHA-256 of the executable. As a method check, the same command on the 0.3.286 Linux x64 archive gives the digest that is on `master` (`fe503f65…`). The Codex 0.160.0 archive also gives the `master` digest (`12eb3e81…`). - The extracted executables report `codex-cli 0.170.0` and `2.1.328 (Claude Code)`. - The Codex 0.170.0 Linux x64 archive no longer contains `codex-resources/zsh/bin/zsh`. Paperclip does not reference that path. - The Agent SDK 0.3.328 `optionalDependencies` have the same platform set as 0.3.286. The Codex 0.170.0 `optionalDependencies` use the same `npm:@openai/codex@<version>-<platform>` aliases. - Bridge link check: I installed `@agentclientprotocol/claude-agent-acp@0.73.0` with an override to Agent SDK 0.3.328 and imported its entry module. Node linked all of the named SDK imports, and the import completed. Real Codex qualification (no model turn, no credentials): - `PAPERCLIP_TEST_CODEX_BINARY=<installed 0.170.0 Linux x64 binary> node --import ./server/node_modules/tsx/dist/loader.mjs scripts/tests/native-cleanup-paginated-codex.mjs` passed: `green: true`, with the expected red control and paginated `thread/resume` through the real 0.170.0 `app-server`. The installed binary digest matches the pinned digest. Focused suites (Linux x64, Node 25.9.0, local `pnpm install --no-frozen-lockfile`): - `cd packages/paperclip-runner && pnpm run typecheck:typescript` passed, including `check:acpx-profiles`. - `npx tsc --noEmit` passed in `packages/adapters/codex-local` and `packages/adapters/claude-local`. - `packages/adapters/codex-local`: 625 passed. `packages/adapters/claude-local`: 419 passed, 1 skipped. - `node --test`: `acpx-codex-package-contract` 9 passed, `controlled-evals/controller` 77 passed, `scripts/acpx-patch-packaging` 26 passed, `scripts/__tests__/grok-public-install-sandbox` 27 passed. - `server`: `acpx-qualification`, `codex-runtime-compatibility`, and `codex-model-fallback` 110 passed. `native-session-executor` 1541 passed, 1 failed. The failure (`compares export process compatibility … db.transaction is not a function`) also fails on unchanged `master` on this host. - `packages/paperclip-runner` vitest (`installation-integrity`, `qualified-profiles`, `codex-security-config`, `native-execution`, `native-backend-factory`): 283 passed, 25 failed. All 25 failures are in `installation-integrity.test.ts` with "ACPX provider lifetime guardian failed to start". The same 25 tests fail on unchanged `master` on this host (master fails 30 here). Rust (toolchain 1.97.1 from `rust-toolchain.toml`, Linux x64): - `cargo test -p paperclip-runner-core --lib`: 658 passed, 2 failed, 4 ignored. `warm_run_attachment_reuses_the_provider_ingress_listener` also fails on unchanged `master` on this host. `reaping_stops_a_dead_runners_provider_and_its_escaped_tool_job` is flaky here: on this branch it passed 2 of 3 reruns. - `cargo test -p paperclip-runner-core --test acpx_warm_attachment --test native_provider_backend`: 7 and 45 passed. - The new and changed saved-session tests pass: `a_session_saved_by_the_previous_agent_runtime_is_refused_by_name`, `unrestorable_saved_sessions_keep_strict_bindings_and_name_their_class`, and `a_settled_session_saved_by_the_previous_acpx_release_continues`. `rustfmt --check` passes. - `server`: `native-session-resume.test.ts` and `acpx-qualification.test.ts` 110 passed, 2 skipped. Both new resume cases run and pass. Not run here: - `native-provider-startup-codex.mjs`, because it needs a compiled `paperclip-runnerd`. The trusted CI runner workflow covers startup and session-resume probes. - The Docker image build and any live model turn. A live Fable 5.2 and GPT-6.2 test follows the staging image rollout. ## Saved sessions from the previous release This change keeps the ACPX bridge command digests and profile versions. It changes `agentRuntimeVersion` in the `claude` and `codex` ACPX profiles. That field is part of the saved session identity. The previous release saved sessions with Agent SDK 0.3.286 or Codex 0.160.0. This build refuses those saved sessions. It does not migrate them. - **Next run (the usual case):** the saved provider descriptor names the old runtime. `rebindNativeSessionCheckpoint` does not match it, so the next run starts a fresh provider session in the same workspace with the complete handoff prompt. No run fails. The earlier provider conversation does not carry over. - **A run in flight at the deploy (settled or mid-turn):** the runner restore refuses the saved descriptor with the permanent class `provider_state_incompatible`. The server reports it as `native_provider_state_incompatible` and stops automatic retries. The runner opens no provider and keeps the saved state bytes and the workspace. The next run on the task starts a fresh provider session. - **Native Codex (`codex_app_server`) and OpenCode** sessions do not record this field, so their resume decision does not change. After a new image is promoted, native Codex resumes a saved thread with Codex 0.170.0 instead of 0.160.0. This pull request does not test that cross-version thread resume. New tests: - `acpx_provider_backend.rs`: `a_session_saved_by_the_previous_agent_runtime_is_refused_by_name` covers settled Claude and Codex sessions and a Claude turn interrupted mid-run by the deploy. `unrestorable_saved_sessions_keep_strict_bindings_and_name_their_class` has a new `agent_runtime_release` case. Each case checks the named class, that no provider session opens, and that the saved bytes do not change. - `native-session-resume.test.ts`: "a session saved by the previous Claude or Codex ACPX runtime" checks that a same-release session resumes, and that a session saved with Agent SDK 0.3.286 or Codex 0.160.0 starts fresh in the same workspace. ## Risks - Medium. Every Paperclip Runner Claude and Codex run uses the new executables. The digests, generated profiles, image probes, and window must agree. They agree locally, and CI runs the Rust and runner suites again. - Claude Code 2.1.287 through 2.1.328 change some headless defaults. I checked each one against Paperclip: - 2.1.302: `-p` and Agent SDK sessions with no permission mode start in `default` mode on third-party providers. Paperclip always sets a mode (`bypassPermissions` or `default`), so this does not apply. - 2.1.299: MCP allow rules now match only the whole server name. Paperclip already writes `mcp__<server>__*` and exact `mcp__paperclip__<tool>` rules. - 2.1.302: fork subagents are on by default in `-p` and the Agent SDK, as in the terminal. This pull request keeps the upstream default and does not set `CLAUDE_CODE_FORK_SUBAGENT=0`. Reviewers can ask to keep them off. - 2.1.299 and later: stdio MCP connections negotiate MCP protocol 2026-07-28 first and fall back to the older protocol for servers that do not answer. - Agent SDK 0.3.328 is less than one day old. If a regression appears, revert this pull request to return to 0.3.286 and Codex 0.160.0. - Sandbox images built before this change still carry Codex 0.160.0 and Claude Code 2.1.286. They stay accepted. On those images, Fable 5.2 and GPT-6.2 keep the existing named errors and fallbacks until a new image is promoted. - Until the refresh bot updates `pnpm-lock.yaml` on `master`, a local `--frozen-lockfile` install fails, as with the previous pin refreshes. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude, model ID `claude-opus-5-5`, through Claude Code with tool use (shell, file edit, `gh`) and code execution. The context window and reasoning mode are not reported in this session. - The registry archives, digests, release notes, configuration schemas, and changelog were read directly. No model output was used as a source for those facts. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [ ] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: devinfoley <139239+devinfoley@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
215 lines
16 KiB
Markdown
215 lines
16 KiB
Markdown
---
|
|
title: Environment Variables
|
|
summary: Full environment variable reference
|
|
---
|
|
|
|
All environment variables that Paperclip uses for server configuration.
|
|
|
|
## Server Configuration
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `PORT` | `3100` | Server port |
|
|
| `PAPERCLIP_BIND` | `loopback` | Reachability preset: `loopback`, `lan`, `tailnet`, or `custom` |
|
|
| `PAPERCLIP_BIND_HOST` | (unset) | Required when `PAPERCLIP_BIND=custom` |
|
|
| `HOST` | `127.0.0.1` | Legacy host override; prefer `PAPERCLIP_BIND` for new setups |
|
|
| `DATABASE_URL` | (embedded) | PostgreSQL connection string |
|
|
| `PAPERCLIP_HOME` | `~/.paperclip` | Base directory for all Paperclip data |
|
|
| `PAPERCLIP_INSTANCE_ID` | `default` | Instance identifier (for multiple local instances) |
|
|
| `PAPERCLIP_DEPLOYMENT_MODE` | `local_trusted` | Runtime mode override |
|
|
| `PAPERCLIP_DEPLOYMENT_EXPOSURE` | `private` | Exposure policy when deployment mode is `authenticated` |
|
|
| `PAPERCLIP_API_URL` | (auto-derived) | Paperclip API base URL. When set externally (e.g., via Kubernetes ConfigMap, load balancer, or reverse proxy), the server preserves the value instead of deriving it from the listen host and port. Useful for deployments where the public-facing URL differs from the local bind address. |
|
|
| `PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL` | (board public origin) | Optional HTTPS origin for native chat provider webhooks when ingress and the board use different hosts. Must have no credentials, path, query, or fragment; invalid configuration refuses startup. Used only for provider callback URLs, not board links, authentication, trusted hosts, or identity confirmation. In `authenticated` mode with `private` exposure, also add the ingress hostname to `PAPERCLIP_ALLOWED_HOSTNAMES`. Otherwise the private-hostname guard rejects provider callbacks with 403 before they reach the webhook route. The guard reads `X-Forwarded-Host` before `Host`, so a reverse proxy that rewrites `Host` but forwards the original `X-Forwarded-Host` still gets 403. |
|
|
| `PAPERCLIP_RUNNER_PUBLIC_URL` | (unset) | Explicit `wss://` base URL used only when a remote `paperclip_runner` target dials Paperclip directly. Paperclip appends `/api/runner/v1/connect/<runId>`; the reverse proxy must forward WebSocket upgrades for that route. This value is never inferred from request headers. Daytona ignores it and uses provider ingress. |
|
|
| `PAPERCLIP_RUNNER_CA_BUNDLE_PATH` | (unset) | Optional PEM CA bundle for direct runner WSS. Platform roots remain enabled. There is no insecure TLS bypass. |
|
|
| `PAPERCLIP_RUNNER_REMOTE_BINARY_PATH` | (host build) | Host-local path to a `paperclip-runnerd` artifact built for the remote target OS and architecture. Required when Paperclip and the remote sandbox do not share a compatible platform; build metadata and the required transport mode are verified before launch. When the sandbox image already has a `paperclip-runnerd` with the same SHA-256, Paperclip uses that copy and does not upload this file. |
|
|
| `PAPERCLIP_RUNNER_REMOTE_CODEX_PATH` | (unset) | Optional host-local path to a Codex executable built for the remote target OS and architecture. For remote Codex-backed runners, Paperclip stages and verifies this executable beside `paperclip-runnerd`. |
|
|
| `PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC` | (unset) | Optional pinned npm package spec (for example, `@openai/codex@0.170.0`) installed inside each fresh remote lease when its Codex harness is not baked into the sandbox image. Mutually exclusive with `PAPERCLIP_RUNNER_REMOTE_CODEX_PATH`; Paperclip verifies the installed executable before starting `runnerd`. |
|
|
| `PAPERCLIP_RUNNER_REMOTE_PROVIDER_PACK_PATH` | `/opt/paperclip-runner/provider-pack` in Docker; otherwise unset | Host-local path to the immutable provider pack built by `pnpm --filter @paperclipai/paperclip-runner build:provider-pack`. Stamped standard Docker images include the pack; downstream compositions and the `cloud` target inherit it. Unstamped local Docker builds skip pack generation. The pack includes its target-built Node 24.11+ runtime, locked production dependencies, OpenCode proxy/executable, and ACPX sidecar. Remote OpenCode and ACPX fail closed without it. A preinstalled pack is accepted only when its complete digested manifest matches this build-owned pack; otherwise Paperclip stages this pack into the sandbox. |
|
|
| `PAPERCLIP_HIDDEN_SETTINGS` | (unset) | Comma-separated settings surfaces to hide from the UI and floor at the API, for operators hosting Paperclip for others (managed cloud, internal shared server). See [Hiding settings surfaces](#hiding-settings-surfaces). |
|
|
| `PAPERCLIP_SETTING_DEFAULTS` | (unset) | JSON object replacing the schema default of selected instance settings, for hosting operators. See [Operator setting defaults](#operator-setting-defaults). |
|
|
| `PAPERCLIP_DEBUG_WORK_SIGNALS` | (unset) | Diagnostic only. Comma-separated allowlist of work-signal topics, each optionally followed by `:N` (for example `stranded-assignments:10,run-dispatch`). For each listed topic the server writes JSON lines to stderr: every work signal (topic and hint), with the caller stack on one signal in N (default 20); remote and reconnect notifications; direct settled publishes; and the recovery queues' loads, checks and direct wakes (direct wakes always carry the caller stack). Logged values are internal ids only (company, issue, run), never secrets or user identifiers. Stack frames keep their raw file and line positions, so bundled builds map them offline with that build's source map. Each topic and event pair is capped at 10 lines per second; a `suppressed` line names the dropped event and its count. The value is read once at startup, so enabling or changing it requires a restart. Unset or empty disables it completely. |
|
|
|
|
Daytona connectivity for `paperclip_runner` uses authenticated provider
|
|
WebSocket ingress and follows the instance experimental setting
|
|
`enableNativeRunner` (default `false`). There is no separate ingress opt-in.
|
|
Disabling Paperclip Runner blocks fresh native starts while persisted native
|
|
runs retain their recovery path. The deprecated `enableRunnerPreviewIngress`
|
|
key remains accepted in stored and managed configuration for version-skew
|
|
compatibility, but it has no runtime effect. The setting has no effect on
|
|
legacy adapters or callback bridges.
|
|
|
|
### Webhook-only chat ingress
|
|
|
|
Keep `PAPERCLIP_PUBLIC_URL` (or the explicit authentication public URL) pointed
|
|
at the actual board. If the board is private, set
|
|
`PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL=https://chat-ingress.example.com` and forward
|
|
only `POST /api/chat-webhooks/*` from that host. Provider signatures still gate
|
|
ingress; this variable does not expose routes or grant provider access.
|
|
Never forward the private `local_trusted` board through a public tunnel.
|
|
|
|
In Paperclip Cloud, chat callback URLs and account-linking URLs follow the
|
|
instance's signed canonical origin after a warm instance is claimed, without
|
|
requiring a restart. An explicit `PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL` still takes
|
|
precedence for provider callbacks only; board links follow the claimed origin.
|
|
Existing provider-side callback settings must be updated if they were created
|
|
with an old URL.
|
|
|
|
Task links in external messages require an externally safe HTTPS board URL.
|
|
Local/private board URLs are omitted with instructions to open the task in
|
|
Paperclip; the public webhook host is never substituted for the board. Identity
|
|
confirmation stays on the board and requires the user to be able to reach it.
|
|
|
|
### Preinstalled remote runner images
|
|
|
|
Remote sandbox images may preinstall `paperclip-runnerd`, `codex`, and the
|
|
provider pack at `/opt/paperclip-runner/provider-pack` instead of
|
|
paying the upload and npm-install cost on every fresh lease. Put both executable
|
|
names on the sandbox user's `PATH`; `$HOME/.local/bin` is checked explicitly
|
|
before `PATH`. Paperclip verifies runner build metadata, the selected PRP
|
|
transport capability, Codex startup, the provider-pack digest, exact harness
|
|
pins, Node compatibility, and packaged bridge digests before linking artifacts
|
|
into the run-specific runtime directory. A missing or incompatible executable falls back
|
|
to `PAPERCLIP_RUNNER_REMOTE_BINARY_PATH` and
|
|
`PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC` (or
|
|
`PAPERCLIP_RUNNER_REMOTE_CODEX_PATH`) without changing the selected transport.
|
|
OpenCode and ACPX instead fall back only to
|
|
`PAPERCLIP_RUNNER_REMOTE_PROVIDER_PACK_PATH`; they never start a provider
|
|
process on the Paperclip host for a remote target.
|
|
The Daytona environment editor's **Configure image** action can create this
|
|
image without a separate container registry: install the executables in its
|
|
setup sandbox, finish setup, and Paperclip captures and promotes the resulting
|
|
Daytona snapshot for future leases.
|
|
|
|
### Hiding settings surfaces
|
|
|
|
`PAPERCLIP_HIDDEN_SETTINGS` takes keys from the registry in
|
|
`packages/shared/src/settings-visibility.ts`:
|
|
|
|
- Any instance settings page: `instance.profile`, `instance.environments`,
|
|
`instance.access`, `instance.experimental`,
|
|
`instance.plugins`, `instance.adapters` — removed from navigation and
|
|
routing (the General page is the settings root and stays visible). Hiding
|
|
`instance.access`, `instance.plugins`, or `instance.adapters` also floors
|
|
their management endpoints with `403 settings_operator_managed`; hiding
|
|
`instance.experimental` floors every experimental toggle write.
|
|
- Any Instance → General section: `instance.general.censorUsernameInLogs`,
|
|
`instance.general.backupRetention`,
|
|
`instance.general.feedbackDataSharingPreference` (each also rejects
|
|
value-changing writes via `PATCH /api/instance/settings/general`), plus the
|
|
UI-only `instance.general.deploymentStatus` and `instance.general.signOut`.
|
|
- Any experimental toggle: `instance.experimental.<flagKey>` (e.g.
|
|
`instance.experimental.enableSmokeLab`) — the card disappears and
|
|
value-changing writes are rejected.
|
|
- All current and future experimental toggles: `instance.experimental.*`.
|
|
Add `!instance.experimental.<flagKey>` entries to leave specific controls
|
|
available. The server expands this policy against its own feature catalog,
|
|
so new toggles stay hidden without an environment change. The Experimental
|
|
page remains available. Exceptions only apply to the wildcard; an explicit
|
|
hidden toggle or `instance.experimental` page restriction always wins,
|
|
regardless of entry order. Unknown exceptions are logged and ignored.
|
|
- Any top-level company settings page: `company.members`, `company.invites`,
|
|
`company.secrets`, `company.export`, `company.import` — removed from the
|
|
settings sidebar, tab bar, and routing (the company General page is the
|
|
settings root and stays visible). These are UI-visibility keys: the
|
|
membership, invite, secret, and export APIs stay live for agents and
|
|
integrations. `company.import` is the exception — hiding it also floors
|
|
every company-import route with `403 settings_operator_managed`. On
|
|
cloud-managed instances import is floored unconditionally with
|
|
`403 cloud_managed`, independent of this variable.
|
|
- A single tab of the Secrets page: `company.secrets.vaults` (Provider
|
|
vaults) and `company.secrets.proposals` (Proposals) — the tab disappears
|
|
while the rest of the page stays up. UI-visibility only; the secret
|
|
provider-config and proposal APIs stay live for agents and integrations.
|
|
|
|
- `workspaces.isolation` hides project execution-workspace policy, task and
|
|
routine workspace selectors, pipeline workspace overrides, isolated re-issue
|
|
actions, and the execution-workspace Configuration tab (including direct
|
|
links). Workspace navigation, files, status, and runtime access stay available.
|
|
This key only controls UI visibility: it does not disable isolation, change
|
|
saved policies, or block APIs used by agents. New tasks and routine runs omit
|
|
hidden draft overrides so the server applies the existing defaults. Tasks
|
|
launched from a workspace or parent task keep that explicit context. Hide the two
|
|
experimental isolation toggles separately when the operator manages them.
|
|
|
|
Unknown keys are logged and ignored, so one list can be rolled across a fleet
|
|
of mixed app versions, and retired keys (like `instance.heartbeats`, whose
|
|
page was removed) can stay in an operator list without breaking older or
|
|
newer releases. With the variable unset nothing is hidden and behavior
|
|
is identical to earlier releases. Hiding a toggle does not change its value;
|
|
pair hiding with the desired default where it matters (for general settings,
|
|
see [Operator setting defaults](#operator-setting-defaults)).
|
|
|
|
For example, this allows only the Environments control and keeps the Plugins
|
|
settings page hidden:
|
|
|
|
```sh
|
|
PAPERCLIP_HIDDEN_SETTINGS='instance.plugins,instance.experimental.*,!instance.experimental.enableEnvironments'
|
|
```
|
|
|
|
`GET /api/health` returns the expanded concrete keys in `hiddenSettings`.
|
|
The UI and settings API use the same restrictions. Reads and same-value
|
|
echoes remain allowed; changing a hidden value returns
|
|
`403 settings_operator_managed`.
|
|
|
|
Older images that predate wildcard support ignore the wildcard and exceptions.
|
|
Keep their explicit hidden-toggle entries during an upgrade, or upgrade all
|
|
images before replacing an explicit list. Once every image supports this
|
|
syntax, the wildcard and its exceptions are sufficient. A recognized exception
|
|
without a wildcard has no effect.
|
|
|
|
### Operator setting defaults
|
|
|
|
`PAPERCLIP_SETTING_DEFAULTS` takes a JSON object whose fields come from the
|
|
registry in `packages/shared/src/setting-defaults.ts` (currently
|
|
`feedbackDataSharingPreference`). The operator value substitutes for the
|
|
schema default at read time: any field whose effective value is still the
|
|
schema default resolves to the operator value, while an explicit non-default
|
|
user choice always wins. The overlay is never persisted, so unsetting the
|
|
variable restores stock behavior wherever a user has not chosen otherwise.
|
|
A client that writes back the full settings object it read does not persist
|
|
the operator value either: writing the operator value over a still-unchosen
|
|
field is treated as an echo of the overlay and the field stays unchosen.
|
|
|
|
Example: `PAPERCLIP_SETTING_DEFAULTS='{"feedbackDataSharingPreference":"allowed"}'`
|
|
defaults AI feedback sharing to allowed; pairing it with
|
|
`instance.general.feedbackDataSharingPreference` in `PAPERCLIP_HIDDEN_SETTINGS`
|
|
also hides the control and floors value-changing writes.
|
|
|
|
Unknown field names are logged and ignored (mixed-version fleet safe).
|
|
Malformed JSON or an invalid value for a known field refuses startup — policy
|
|
configuration fails closed.
|
|
|
|
## Secrets
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `PAPERCLIP_SECRETS_MASTER_KEY` | (from file) | 32-byte encryption key (base64/hex/raw) |
|
|
| `PAPERCLIP_SECRETS_MASTER_KEY_FILE` | `~/.paperclip/.../secrets/master.key` | Path to key file |
|
|
| `PAPERCLIP_SECRETS_STRICT_MODE` | `false` | Require secret refs for sensitive env vars |
|
|
|
|
## Agent Runtime (Injected into agent processes)
|
|
|
|
These are set automatically by the server when invoking agents:
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `PAPERCLIP_AGENT_ID` | Agent's unique ID |
|
|
| `PAPERCLIP_COMPANY_ID` | Company ID |
|
|
| `PAPERCLIP_API_URL` | Paperclip API base URL (inherits the server-level value; see Server Configuration above) |
|
|
| `PAPERCLIP_API_KEY` | Short-lived JWT for API auth |
|
|
| `PAPERCLIP_RUN_ID` | Current heartbeat run ID |
|
|
| `PAPERCLIP_TASK_ID` | Issue that triggered this wake |
|
|
| `PAPERCLIP_WAKE_REASON` | Wake trigger reason |
|
|
| `PAPERCLIP_WAKE_COMMENT_ID` | Comment that triggered this wake |
|
|
| `PAPERCLIP_APPROVAL_ID` | Resolved approval ID |
|
|
| `PAPERCLIP_APPROVAL_STATUS` | Approval decision |
|
|
| `PAPERCLIP_LINKED_ISSUE_IDS` | Comma-separated linked issue IDs |
|
|
|
|
## LLM Provider Keys (for adapters)
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `ANTHROPIC_API_KEY` | Anthropic API key (for Claude Code adapter) |
|
|
| `OPENAI_API_KEY` | OpenAI API key (for Codex adapter) |
|