0936990a58ce819da8fd5e8ceb2e9a5b4d4a70ad
12 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Darren Davison
|
9802636be3 |
build(docker): bundle Gemini CLI in image for gemini_local adapter (#7693)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work, and it runs agents through pluggable adapters. > - One of those adapters, `gemini_local` (`packages/adapters/gemini-local/`), runs Google's Gemini CLI on the same host as the server. > - For local (in-container) execution, the adapter only probes `PATH` for the binary (`packages/adapter-utils/src/execution-target.ts`); it does **not** auto-install — only `sandbox` transport targets install on demand via `SANDBOX_INSTALL_COMMAND`. > - The production Docker image bakes in `claude`, `codex`, and `opencode` so their `*_local` adapters work out of the box, but `gemini` was never added — so `gemini_local` fails inside the container with a missing-binary error. > - This PR adds `@google/gemini-cli@latest` to the image's global install so `gemini_local` works locally like the other bundled CLIs, sets `GEMINI_SANDBOX=false` for safe in-container CLI use, and documents all bundled CLIs. > - The benefit is plug-and-play Gemini support in Docker with no per-deployment CLI install step, plus accurate docs (including a previously-undocumented `opencode` bundle) and a heads-up about Google's imminent unrestricted-API-key block. ## Linked Issues or Issue Description No existing issue. Following the **adapter/feature** template fields: - **Capability:** Run the existing `gemini_local` adapter inside the official Docker image without a manual CLI install. - **Problem/motivation:** The image pre-installs `claude`, `codex`, and `opencode`, but not `gemini`. Because local execution probes `PATH` and never auto-installs (only sandbox targets do), `gemini_local` runs fail in-container with a missing-binary error. Operators currently have to maintain a forked image. - **Proposed solution:** Add `@google/gemini-cli@latest` to the existing global `npm install` line; set `GEMINI_SANDBOX=false` in `ENV`. - **Alternatives considered:** Runtime install at container start (slower, network-dependent, inconsistent with how the other three CLIs are handled). **Related / superseded PRs** (both make the same Dockerfile change and can be closed if this merges): - #5912 — `fix(docker): install gemini-cli and normalize persistent volume permissions`. Same Dockerfile line, but also bundles unrelated volume-permission and heartbeat-test changes, and a maintainer noted it now has a merge conflict. I corrected Greptile's `GEMINI_SANDBOX` reasoning there and it was re-scored 5/5 (see [resolved thread](https://github.com/paperclipai/paperclip/pull/5912#discussion_r3367332785)) — this PR is the rebased, docs-complete, single-purpose version of that change. - #2731 — `Added @google/gemini-cli to the Dockerfile`. One-liner, now stale and merge-conflicting (predates the `opencode-ai` addition). > **Note for Greptile:** the `--sandbox=none` reasoning for the Gemini CLI sandbox concern was already validated on #5912's `Dockerfile:59` thread and accepted (re-scored 5/5). This PR additionally bakes `GEMINI_SANDBOX=false` into `ENV` as defense-in-depth, so the concern is covered both at the adapter layer and the image layer. ## What Changed - **Dockerfile:** add `@google/gemini-cli@latest` to the production global npm install (after `opencode-ai`). - **Dockerfile:** add `GEMINI_SANDBOX=false` to the `ENV` block (matches the existing `OPENCODE_ALLOW_ALL_MODELS=true` precedent) so a manually-invoked `gemini` inside the container does not attempt a Docker-in-Docker sandbox. - **docs/deploy/docker.md:** rename the section to "Local Adapter CLIs in Docker"; list all four bundled CLIs mapped to their adapter type keys (fixes a pre-existing gap — `opencode` was bundled but undocumented); add `GEMINI_API_KEY` to the example; document per-provider credentials, the `GEMINI_SANDBOX=false` default, and Google's 2026-06-19 unrestricted-key block with the `gemini auth login` (OAuth) alternative. ## Verification - `npm view @google/gemini-cli` confirms the package exists, provides the `gemini` bin, and requires Node `>=20` (the base image is Node 22 LTS). ✅ - Adapter already disables the CLI sandbox per run: `packages/adapters/gemini-local/src/server/execute.ts` pushes `--sandbox=none` whenever `config.sandbox` is false (the default). ✅ - Confirmed neither file was modified on `upstream/master`, so this rebases cleanly with no conflicts. ✅ - Full image build is exercised by CI. (I did not run the multi-stage `docker build` locally; the change adds one package to an existing, working `npm install` line.) - Reviewer manual check: `docker build -t paperclip-local . && docker run --rm paperclip-local gemini --version` should print the CLI version. ## Risks - **Low risk.** Adds one npm package to an existing global install and one inert env var; no application code paths change. - Minor image-size increase from the additional CLI (consistent with the three already bundled). - `@latest` is unpinned — intentionally consistent with the sibling `@anthropic-ai/claude-code@latest` / `@openai/codex@latest` on the same line; pinning all of them is a separate decision out of scope here. ## Model Used Claude Opus 4.8 (model ID `claude-opus-4-8`, 1M-context variant), via Claude Code with tool use / agentic file editing and web research. ## 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 OR (b) described the issue in-PR following the relevant issue template - [ ] I have run tests locally and they pass (no unit tests cover the Dockerfile; package/bin/engine verified via `npm view`, full build runs in CI) - [ ] I have added or updated tests where applicable (N/A — Docker image + docs change) - [ ] If this change affects the UI, I have included before/after screenshots (N/A) - [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 (pending CI run on this PR) - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (pending review) - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|
Dotta
|
778e775c35 |
Add secrets provider vaults and remote import (#5429)
## Thinking Path > - Paperclip orchestrates AI-agent companies and needs secrets handling to work across local development, hosted operators, and governed agent execution. > - The affected subsystem is the company-scoped secrets control plane: database schema, server services/routes, CLI workflows, and the Secrets settings UI. > - The gap was that secrets were local-only and operators could not manage provider vaults or import existing remote references without exposing plaintext. > - This branch adds provider vault configuration plus an AWS Secrets Manager remote-import path while preserving company boundaries, binding context, and audit trails. > - I kept the PR to a single branch PR, removed unrelated lockfile/package drift, rebased the full branch onto the current `public-gh/master`, and addressed fresh Greptile findings. > - The benefit is a reviewable implementation of provider-backed secrets with focused tests covering provider selection, import conflicts, deleted secret reuse, rotation guards, and AWS signing behavior. ## What Changed - Added provider vault support for company secrets, including provider config storage, default vault handling, health checks, binding usage, access events, and remote import preview/commit. - Added an AWS Secrets Manager provider using SigV4 request signing, bounded request timeouts, namespace guardrails, cached runtime credential resolution, and external-reference linking without plaintext reads. - Added Secrets UI surfaces for vault management and remote import, plus CLI/API documentation for setup and operations. - Stabilized routine webhook secret binding paths and SSH environment-driver fixture bindings discovered during verification. - Addressed Greptile and CI findings: no lockfile/package drift, monotonic migration metadata, disabled-vault default races, soft-deleted secret hiding/recreate behavior, remove behavior with disabled vaults, soft-deleted external-reference re-import, non-active rotation guards, managed-secret soft deletion through PATCH, and per-call AWS SDK credential client churn. - Rebased this branch onto `public-gh/master` at `0e1a5828` and force-pushed with lease to keep this as the single PR for the branch. ## Verification - `git fetch public-gh master` - `git rebase public-gh/master` - `git diff --name-only public-gh/master...HEAD | grep '^pnpm-lock\.yaml$' || true` confirmed `pnpm-lock.yaml` is not in the PR diff. - Confirmed migration ordering: master ends at `0081_optimal_dormammu`; this PR adds `0082_dry_vision` and `0083_company_secret_provider_configs`. - Inspected migrations for repeat safety: new tables/indexes use `IF NOT EXISTS`; foreign keys are guarded by `DO $$ ... IF NOT EXISTS`; column additions use `ADD COLUMN IF NOT EXISTS`. - `pnpm -r typecheck` passed before the Greptile follow-up commits. - `pnpm test:run` ran the full stable Vitest path before the Greptile follow-up commits; it completed with 3 timing-related failures under parallel load: `codex-local-execute.test.ts`, `cursor-local-execute.test.ts`, and `environment-service.test.ts`. - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/codex-local-execute.test.ts src/__tests__/cursor-local-execute.test.ts src/__tests__/environment-service.test.ts` passed on targeted rerun (`24/24`). - `pnpm build` passed before the Greptile follow-up commits. Vite reported existing chunk-size/dynamic-import warnings. - After Greptile follow-up commits: `pnpm --filter @paperclipai/server exec vitest run src/__tests__/secrets-service.test.ts` passed (`26/26`). - After Greptile follow-up commits: `pnpm --filter @paperclipai/server exec vitest run src/__tests__/aws-secrets-manager-provider.test.ts src/__tests__/secrets-service.test.ts` passed (`39/39`). - After Greptile follow-up commits: `pnpm --filter @paperclipai/server typecheck` passed. - Captured Storybook screenshots from `ui/storybook-static` for visual review. - Latest PR checks on `5ca3a5cf`: `policy`, serialized server suites 1/4-4/4, `Canary Dry Run`, `e2e`, `security/snyk`, and `Greptile Review` pass; aggregate `verify` is still registering the completed child checks. - Greptile review loop continued through the latest requested pass; all Greptile review threads are resolved and the latest `Greptile Review` check on `5ca3a5cf` passed with 0 comments added. ## Screenshots Before: the provider-vault and remote-import surfaces did not exist on `master`; these are after-state screenshots from the Storybook fixtures.    ## Risks - Migration risk: this adds new secret provider tables and extends existing secret rows. The migrations were checked for monotonic ordering and idempotent guards, but reviewers should still inspect upgrade behavior carefully. - Provider risk: AWS support uses direct SigV4 requests. Automated tests cover signing, request timeouts, vault-config selection, namespace guardrails, pending-version archival, sanitized provider errors, and service-level cleanup paths. A real-vault AWS smoke test remains deployment validation for an operator with AWS credentials rather than an unverified merge blocker in this local branch. - UI risk: the Secrets page and import dialog are large new surfaces; screenshots are included above for reviewer inspection. - Verification risk: the full local stable test command hit parallel-load timing failures, although the exact failed files passed when rerun directly. - Operational risk: remote import intentionally avoids plaintext reads; operators must understand that imported external references resolve at runtime and may fail if AWS permissions change. > 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 - OpenAI Codex, GPT-5 coding agent with local shell/tool use in the Paperclip worktree. Exact context-window size was not exposed by the runtime. ## 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 - [ ] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
Neeraj Kumar Singh B
|
f0f9460d1d |
docs: AWS ECS Fargate deployment runbook (#3897)
## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies and ships
a
> "local-first, cloud-ready" deployment model
> - The deploy docs currently cover local/Docker but not a production
> cloud target, so teams asking "how do I put this behind a real domain"
> have no canonical path
> - We already support Docker images, RDS-compatible Postgres, and an
EFS
> storage profile, so AWS ECS Fargate is a natural fit
> - Without a runbook, each team reinvents VPC, security groups, TLS,
and
> secrets wiring and usually gets at least one step wrong
> - This pull request adds `docs/deploy/aws-ecs.md`, an ECS
task-definition
> template, and an `.env.aws.example`, cross-linked from the deploy
overview
> - The benefit is a single, reproducible ~$110/mo path to a production
> deployment, plus a full teardown for throwaway environments
## What Changed
- New `docs/deploy/aws-ecs.md` — an 11-step ECS Fargate runbook covering
ECR,
VPC, RDS, EFS, Secrets Manager, IAM, ALB, and ECS service with the
deployment circuit breaker enabled
- New `docker/ecs-task-definition.json` — Fargate-ready task definition
with
`<ACCOUNT_ID>`, `<REGION>`, `<EFS_ID>`, `<DOMAIN>` placeholder tokens
- New `docker/.env.aws.example` — documents every non-secret env var the
ECS deployment needs
- `docs/deploy/overview.md` — one-line cross-reference to the new guide
- Greptile feedback addressed in follow-up commits:
- `containerName` in the service-create call now matches
`paperclip-server` in the task definition
- HTTP :80 listener added that 301-redirects to :443
- Dedicated RDS DB subnet group created before `create-db-instance`
- EFS teardown polls on mount-target deletion instead of `sleep 30`
## Verification
- Walked every step of the runbook against the task definition to
confirm
variable names (`$ALB_SG`, `$ECS_SG`, `$RDS_SG`, `$EFS_SG`, `$TG_ARN`,
`$LISTENER_ARN`, `$HTTP_LISTENER_ARN`, `$EFS_ID`, `$RDS_ENDPOINT`, etc.)
are
defined before they are referenced
- Confirmed the `containerName` in Step 10 (`paperclip-server`) matches
`docker/ecs-task-definition.json` line 11
- Confirmed the `sed` placeholder substitution in Step 8 matches the
tokens
in the task definition template
- Teardown order was checked in reverse-dependency order: ECS service →
listeners → target group → ALB → RDS (waits for deletion) → DB subnet
group → EFS mount targets (polled) → EFS → secrets → SGs → ECR → IAM →
log group
## Risks
- **Low risk for the repo.** Docs-only change plus two template files
under
`docker/`; no runtime code paths are touched and nothing is imported by
the build.
- **Risk for users who follow the runbook:** AWS bills accrue
immediately
once RDS/ALB/EFS exist. The runbook calls this out and includes a full
teardown procedure. Placeholder tokens (`<ACCOUNT_ID>`, `<REGION>`,
`<EFS_ID>`, `<DOMAIN>`) are documented so nothing is silently
hard-coded.
## Model Used
- Claude (Anthropic), model `claude-opus-4-6`, ~200K context window,
extended thinking mode on, used with tool access (file edit, shell) via
Claude Code. The Greptile follow-up commits were authored the same way.
## 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 run tests locally and they pass — N/A for docs/config
templates; validated by reading
- [x] I have added or updated tests where applicable — N/A for docs
- [x] If this change affects the UI, I have included before/after
screenshots — N/A, no UI
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
|
||
|
Chris Farhood
|
b816809a1e |
fix(server): respect externally set PAPERCLIP_API_URL env var (#3472)
## Thinking Path > - Paperclip server starts up and sets internal `PAPERCLIP_API_URL` for downstream services and adapters > - The server startup code was unconditionally overwriting `PAPERCLIP_API_URL` with `http://localhost:3100` (or equivalent based on `config.host`) > - In Kubernetes deployments, `PAPERCLIP_API_URL` is set via a ConfigMap to the externally accessible load balancer URL (e.g. `https://paperclip.example.com`) > - Because the env var was unconditionally set after loading the ConfigMap value, the ConfigMap-provided URL was ignored and replaced with the internal localhost address > - This caused downstream services (adapter env building) to use the wrong URL, breaking external access > - This pull request makes the assignment conditional — only set if not already provided by the environment > - External deployments can now supply `PAPERCLIP_API_URL` and it will be respected; local development continues to work without setting it ## What Changed - `server/src/index.ts`: Wrapped `PAPERCLIP_API_URL` assignment in `if (!process.env.PAPERCLIP_API_URL)` guard so externally provided values are preserved - `server/src/__tests__/server-startup-feedback-export.test.ts`: Added tests verifying external `PAPERCLIP_API_URL` is respected and fallback behavior is correct - `docs/deploy/environment-variables.md`: Updated `PAPERCLIP_API_URL` description to clarify it can be externally provided and the load balancer/reverse proxy use case ## Verification - Run the existing test suite: `pnpm test:run server/src/__tests__/server-startup-feedback-export.test.ts` — all 3 tests pass - Manual verification: Set `PAPERCLIP_API_URL` to a custom value before starting the server and confirm it is not overwritten ## Risks - Low risk — purely additive conditional check; existing behavior for unset env var is unchanged ## Model Used MiniMax M2.7 — reasoning-assisted for tracing the root cause through the startup chain (`buildPaperclipEnv` → `startServer` → `config.host` → `HOST` env var) ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Pawla Abdul (Bot) <pawla@groombook.dev> Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
dotta
|
2a84e53c1b |
Introduce bind presets for deployment setup
Co-Authored-By: Paperclip <noreply@paperclip.ing> |
||
|
Cody (Radius Red)
|
420cd4fd8d |
chore(docker): improve base image and organize docker files
- Add wget, ripgrep, python3, and GitHub CLI (gh) to base image - Add OPENCODE_ALLOW_ALL_MODELS=true to production ENV - Move compose files, onboard-smoke Dockerfile to docker/ - Move entrypoint script to scripts/docker-entrypoint.sh - Add Podman Quadlet unit files (pod, app, db containers) - Add docker/README.md with build, compose, and quadlet docs - Add scripts/docker-build-test.sh for local build validation - Update all doc references for new file locations - Keep main Dockerfile at project root (no .dockerignore changes needed) Co-Authored-By: Paperclip <noreply@paperclip.ing> |
||
|
Dotta
|
e9ffde610b | docs: add tailscale private access guide | ||
|
Dotta
|
09d2ef1a37 |
fix: restore docs deleted in v0.2.3 release, add Paperclip branding
- Restored docs/ directory that was accidentally deleted by `git add -A` in the v0.2.3 release script - Replaced generic "P" favicon with actual paperclip icon using brand primary color (#2563EB) - Added light/dark logo SVGs for Mintlify navbar (paperclip icon + wordmark) - Updated docs.json with logo configuration for dark/light mode - Fixed release.sh to stage only release-related files instead of `git add -A` to prevent sweeping unrelated changes into release commits Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> |
||
|
Dotta
|
28bf5e9e9b | chore: release v0.2.3 | ||
|
Dotta
|
f60c1001ec |
refactor: rename packages to @paperclipai and CLI binary to paperclipai
Rename all workspace packages from @paperclip/* to @paperclipai/* and the CLI binary from `paperclip` to `paperclipai` in preparation for npm publishing. Bump CLI version to 0.1.0 and add package metadata (description, keywords, license, repository, files). Update all imports, documentation, user-facing messages, and tests accordingly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> |
||
|
Dotta
|
cabd16bc70 | docs: sync docs and skills updates from backup branch | ||
|
Forgotten
|
02dc46e782 |
docs: add external documentation site content
Add structured documentation covering quickstart, architecture, core concepts, API reference, adapter guides, CLI commands, deployment options, and operator/developer guides. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> |
