PaperClipAI/docs/deploy/environment-variables.md at 13bae6fa21375ea8301ee09fd9f73ab8b9ff5eda

Jannik/PaperClipAI

0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-07 07:23:08 +02:00

Files

T

DottaandPaperclip 889947c238 feat: add experimental native chat connectors (#13038 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - People also ask agents for work in their existing chat tools.
> - Each external conversation needs one task and a current authorized
source.
> - Retries, Stop, and provider failures must not duplicate work or
expose private data.
> - The first chat PR establishes the opt-in provider and data
contracts.
> - This PR adds experimental channel integration and its durable
control plane.
> - Users can request work from connected channels and inspect delivery
in Paperclip.

## Linked Issues or Issue Description

Refs #13100 and #13092. This is the second of exactly two chat PRs.
Foundation #13100 is merged and changed 143 files. Runner prerequisite
#13092 is also merged. This PR changes 400 files against master, below
the 500-file review limit. It contains no wireframe images or HTML
galleries.

## What Changed

- Add native Slack, GitHub, Microsoft Teams, Telegram, and Discord chat
connections. Keep chat disabled unless the operator enables experimental
chat connectors. Preserve the production GitHub tool connection and its
normal setup path.
- Bind each provider bot identity to one immutable Paperclip agent. Bind
each admitted external conversation to one task. Paperclip owns tasks,
runs, permissions, and audit records.
- Add durable admission, per-conversation queues, questions, task
controls, progress, final replies, images, files, and delivery receipts.
Board comments remain internal unless explicitly sent to the channel.
- Check current identity, provider reach, resource access, credentials,
runtime generation, and exact source before provider effects. Keep
private responses private. Never send raw reasoning, private logs,
credentials, or tool arguments.
- Hold uncertain sends for explicit audited resolution. Make Board
Send-to-channel atomic and idempotent. Keep reconnect and setup
credentials in Paperclip secret storage.
- Preserve current native-runner authority across retries, lost
acknowledgements, and recovery. Keep immutable input and completion
contracts separate from newer user input. Receipt reconciliation cannot
launch a provider.
- Reconcile chat close/new ordering and provider-effect lock order.
Audit resource access changes in the same transaction. Submit only the
selected resource from each UI toggle so stale pages cannot undo
unrelated access changes.
- Drain Codex stdout before certifying process exit. Bound the drain
with the existing shutdown grace. Preserve observed terminal authority
without treating an undrained process as successful or reusable.
- Incorporate master `018ca5da` with its ACP Stop, mobile task layout,
runner packaging, and official lock changes. Preserve dedicated
chat-answer continuations in both directions when ordinary queued
comments are adopted after Stop.
- Fence late adapter readiness behind an earlier Stop for the same run.
Preserve verified cleanup for registered adapters. Handle single Stop,
agent pause, duplicate Stops, and failure release without creating a
false cancellation receipt.
- Incorporate master's `6dd48cad4` wake-queue extraction. Preserve exact
failed-chat retry authorization and lineage, retired question-source
suppression, and the block on generic recovery that would discard the
admitted source. Fresh deferred input retains its separate promotion
path.
- Incorporate master `2a05b5ed3` and its queue-admission extraction,
simplified transaction ports, and separate runner CI job. Preserve exact
durable receipts, actor separation, and dedicated-answer isolation
through the new module. A failed receipt insert rolls back the
accompanying deferred-wake merge.

## Verification

Current head: `afe19299d06253cb628eb398e91d1200ea9f412a`, incorporating
master `2a05b5ed3457ea33efd6895520447d1d97fe98d8`. The conflicts are
resolved. This successor fixes two test-harness boundaries exposed by
CI: per-case route-module preparation and actual durable-save completion
before intentional runner termination. Production code and all existing
test/turn deadlines are unchanged. [Exact-head Greptile
review](https://github.com/paperclipai/paperclip/pull/13038#issuecomment-5587250594)
is **5/5**, completed September 10 at 13:20:55 UTC, with no actionable
findings or open review threads. [Fresh exact-head
CI](https://github.com/paperclipai/paperclip/actions/runs/34481724341)
passes **all 24 jobs**, including Build and both required aggregates.
Normal exact-head guarded merge was attempted and rejected by the
remaining branch approval policy: CODEOWNER review is required and no
human approval is present. Normal **squash auto-merge is enabled** as of
September 10 at 13:36:26 UTC. Requested CODEOWNERS have been notified;
no approval bypass or self-approval was used. Earlier-head results below
remain historical evidence, not qualification of this successor.

- Final exact-head Linux evidence: 995/995 chat integration cases; 36/36
agent-skills routes; 35/35 runner live-session cases, including real
process kill/resume; 1948 runner Vitest cases with three existing
benchmark/platform guards; 870/870 API-authority cases; and 104 browser
cases with four existing optional skips. Rust, conformance/replay, full
repository build, typecheck, canary, all server/workspace shards, and
both required aggregates pass with normal CI concurrency. Earlier failed
attempts remain recorded below.

- Latest test-only qualification: 141/141
route/permissions/authentication cases pass in separate cold forks, with
plain server types and independent review clear. The real-runner suite
passes 35/35, with plain runner types and independent review clear. A
controlled premature-save acknowledgement fails as expected; matching
ownership/effect/process evidence, rejected saves, real turn outcome,
test abort, and pre-kill liveness are covered. No local reproduction of
the original CI scheduling failure is claimed. The preceding [CI
run](https://github.com/paperclipai/paperclip/actions/runs/34479680858)
passes 21/24 jobs, including all 995 Linux chat cases and browser
aggregate (104 passed, four existing optional skips); only Build, the
skills serialized shard, and the required verification aggregate fail.
Its exact-head Greptile review was 5/5. Both failed job logs are
retained.

- Final fixture qualification: all eight focused Discord cases and all
995 chat integration cases pass. The exact modal statement/PID is
observed before taking the real connection lock; the test then proves
its actual blocking relationship before mutation. Original SQL
execution, provider behavior, negative assertions, and 1s/15s timeouts
remain unchanged. Independent review is clear and test/production hashes
remain frozen. The preceding [CI
attempt](https://github.com/paperclipai/paperclip/actions/runs/34477184777)
passed 22 jobs, including Build/runner, typecheck, canary, all other
test shards, and browser aggregate (104 passed, four existing optional
skips); the two fixture failures and failed verification aggregate
remain recorded, not relabeled as a pass.

- Current queue-module composition: 308/308 recovery/batching/queue/Stop
tests; 995/995 full chat integration; 89/89 module tests, including real
PostgreSQL receipt-insert rollback; 24/24 workflow/module-boundary
tests; plain server and UI types. All four actual local process/ACP
browser paths pass in 1.4 minutes. Fresh databases, no skips or retries,
stable reviewed source hashes. The initial boundary failure is retained;
its no-op service wrapper was removed without changing recovery context
or weakening the check. An exploratory standalone test-directory
typecheck fails because its new upstream transformation config is not a
standalone typechecking project; standard CI/build does not invoke it,
and no configuration was weakened to suppress those diagnostics.

- The preceding head `e02a63d462ce5d47433b0aeb632bb6fd20aab1ba` passed
[all 24 CI
jobs](https://github.com/paperclipai/paperclip/actions/runs/34436462958)
and exact-head Greptile review at 5/5. Required CODEOWNER review
prevented its normal merge before master advanced again.

- Final extracted-module composition: 307/307 recovery, batching, queue
and Stop-control tests; 995/995 full chat integration; 49/49 module
tests including eight PostgreSQL adapter cases; and 19/19 issue-update
tests. Plain server types pass. All four actual local process/ACP
browser paths pass in 1.3 minutes. Fresh databases, no skips or retries
in these cohorts, frozen source hashes, and independent review clear.

- The preceding head `3e4e1c1c` passes [all PR CI
jobs](https://github.com/paperclipai/paperclip/actions/runs/34415826820),
including Build and required `ci / verify` and `ci / e2e`. Both the
original Rust failure and the previously load-sensitive lineage fixture
pass with unchanged Linux concurrency. Master advanced afterward and
required this reconciliation.
- Final master composition: 448/448 focused UI tests, 186/186 adapter
tests, 24/24 queue/control tests, and 11/11 packaging tests. Plain UI,
server, shared, and adapter types pass. Token gates and diff checks
pass. Independent server and UI reviews are clear.
- Stop-registration regression: both real-service cases fail against
exact `a95` source and pass with the fix. The full corrected
recovery/control suite passes 265/265. Duplicate-owner and failed-Stop
controls also pass. Plain server types pass. The readiness barrier
prevents provider startup without adding an acknowledgment to an already
terminal run.
- Final qualification strengthens terminal-field equality and repeats
both affected cases successfully on a fresh database. All four actual
local process/ACP browser paths pass again in 1.3 minutes, without skips
or retries. The final screenshot shows Cancelled, a paused subtree,
retained input, and no error toast.
- Two new actual-service regressions fail before the merge fix. They
prove that queued-comment adoption could consume a dedicated chat answer
or add unrelated input to that answer. The fixed four-case cohort
passes, including ordinary upstream continuation and adapter Stop
controls. Full recovery passes 257/257. All four actual local
process/ACP Stop browser flows pass in 1.4 minutes, without skips or
retries, on a fresh database.
- The unchanged runner artifact was qualified with 171/171 transport
tests, 870/870 API-authority tests, conformance 1/1, and replay 11/11.
Six controlled reader tests prove the exit/drain repair. Its local
serial Rust workspace passed 546 top-level cases plus two invoked
helpers; the later passing Linux CI supplies default-concurrency
evidence.
- Prior exact-source full chat integration passes 995/995. Settings
regressions cover concurrent stale pages, 501 destinations, pending
state, rejected updates, and explicit retry. These deterministic tests
do not prove live provider behavior.
- Retained failed attempts and their causes are in the [qualification
log](https://github.com/paperclipai/paperclip/blob/afe19299d06253cb628eb398e91d1200ea9f412a/doc/plans/chat-adapters/2026-09-08-chat-queue-and-webhook-repair.md).
The first merge adapter run timed out while macOS slept for 290 seconds.
Its unchanged repeat passed with a temporary sleep guard. No assertion,
deadline, or CI gate was weakened.

Review commands include `pnpm --filter @paperclipai/server exec vitest
run src/__tests__/heartbeat-process-recovery.test.ts
src/__tests__/issue-queued-comments-routes.test.ts` and `pnpm exec
playwright test --config tests/e2e/playwright.config.ts
tests/e2e/acp-stop-continuation.spec.ts`. Database suites require fresh
disposable databases. See the [browser
runbook](https://github.com/paperclipai/paperclip/blob/afe19299d06253cb628eb398e91d1200ea9f412a/doc/plans/chat-adapters/2026-09-04-chat-adapters-browser-e2e-runbook.md)
for provider setup and separate live acceptance steps.

## Risks

- This remains experimental. Deterministic tests and bounded live
evidence do not establish every provider feature, tenant, permission
layout, or media shape. Teams work-tenant qualification is still open.
- Failed and uncertain provider effects remain visible and can require
operator action. A transport receipt does not prove recipient
visibility.
- Native controller and runner artifacts must remain compatible.
Preserve lease ownership, terminal authority, source binding, and
quarantine during future changes.
- Access and audit rows commit together, but activity notifications
remain best-effort. This is not a new durable event outbox.
- The PR operation does not deploy a live server, replace its runner, or
change provider permissions. Remaining live qualification is documented
in the [temporary
handoff](https://github.com/paperclipai/paperclip/blob/afe19299d06253cb628eb398e91d1200ea9f412a/doc/plans/chat-adapters/2026-09-08-open-qualification-followups.md).

## Model Used

OpenAI Codex assisted with implementation, tool execution, testing, and
review. The work records `gpt-6-astra` assistance. The environment does
not report a context-window size. No private reasoning traces are
included.

## 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
- [x] 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
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-09-10 10:06:45 -05:00

12 KiB

Raw Blame History

title, summary

title	summary
Environment Variables	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.
`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.
`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.153.4`) 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`	(unset)	Host-local path to the immutable provider pack built by `pnpm --filter @paperclipai/paperclip-runner build:provider-pack`. 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.
`PAPERCLIP_SETTING_DEFAULTS`	(unset)	JSON object replacing the schema default of selected instance settings, for hosting operators. See Operator setting defaults.

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.

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

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

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)

12 KiB Raw Blame History