## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies.
> - The environment/runtime layer decides where agent work executes and
how the control plane reaches those runtimes.
> - Today Paperclip can run locally and over SSH, but sandboxed
execution needs a first-class environment model instead of one-off
adapter behavior.
> - We also want sandbox providers to be pluggable so the core does not
hardcode every provider implementation.
> - This branch adds the Sandbox environment path, the provider
contract, and a deterministic fake provider plugin.
> - That required synchronized changes across shared contracts, plugin
SDK surfaces, server runtime orchestration, and the UI
environment/workspace flows.
> - The result is that sandbox execution becomes a core control-plane
capability while keeping provider implementations extensible and
testable.
## What Changed
- Added sandbox runtime support to the environment execution path,
including runtime URL discovery, sandbox execution targeting,
orchestration, and heartbeat integration.
- Added plugin-provider support for sandbox environments so providers
can be supplied via plugins instead of hardcoded server logic.
- Added the fake sandbox provider plugin with deterministic behavior
suitable for local and automated testing.
- Updated shared types, validators, plugin protocol definitions, and SDK
helpers to carry sandbox provider and workspace-runtime contracts across
package boundaries.
- Updated server routes and services so companies can create sandbox
environments, select them for work, and execute work through the sandbox
runtime path.
- Updated the UI environment and workspace surfaces to expose sandbox
environment configuration and selection.
- Added test coverage for sandbox runtime behavior, provider seams,
environment route guards, orchestration, and the fake provider plugin.
## Verification
- Ran locally before the final fixture-only scrub:
- `pnpm -r typecheck`
- `pnpm test:run`
- `pnpm build`
- Ran locally after the final scrub amend:
- `pnpm vitest run server/src/__tests__/runtime-api.test.ts`
- Reviewer spot checks:
- create a sandbox environment backed by the fake provider plugin
- run work through that environment
- confirm sandbox provider execution does not inherit host secrets
implicitly
## Risks
- This touches shared contracts, plugin SDK plumbing, server runtime
orchestration, and UI environment/workspace flows, so regressions would
likely show up as cross-layer mismatches rather than isolated type
errors.
- Runtime URL discovery and sandbox callback selection are sensitive to
host/bind configuration; if that logic is wrong, sandbox-backed
callbacks may fail even when execution succeeds.
- The fake provider plugin is intentionally deterministic and
test-oriented; future providers may expose capability gaps that this
branch does not yet cover.
## Model Used
- OpenAI Codex coding agent on a GPT-5-class backend in the
Paperclip/Codex harness. Exact backend model ID is not exposed
in-session. Tool-assisted workflow with shell execution, file editing,
git history inspection, and local test execution.
## 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 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
## Thinking Path
> - Paperclip is the control plane that runs long-lived AI-agent work in
production.
> - The production container image is the runtime boundary for agent
tools and shell access.
> - In our deployment, Paperclip agents now need a native SSH client and
`jq` available inside the final runtime container.
> - Installing those tools only via ai-rig entrypoint hacks is brittle
and drifts from the image source of truth.
> - This pull request updates the production Docker image itself so the
required binaries are present whenever the image is built.
> - The change is intentionally scoped to the final production stage so
build/deps stages do not gain extra packages unnecessarily.
> - The benefit is a cleaner, reproducible runtime image with fewer
deploy-specific workarounds.
## What Changed
- Added `openssh-client` to the production Docker image stage.
- Added `jq` to the production Docker image stage.
- Kept the package install in the final `production` stage instead of
the shared base stage to minimize scope.
## Verification
- Reviewed the final Dockerfile diff to confirm the packages are
installed in the `production` stage only.
- Attempted local image build with:
- `docker build --target production -t paperclip:ssh-jq-test .`
- Local build could not be completed in this environment because the
local Docker daemon was unavailable:
- `Cannot connect to the Docker daemon at
unix:///Users/roman/.docker/run/docker.sock. Is the docker daemon
running?`
## Risks
- Low risk: image footprint increases slightly because two Debian
packages are added.
- `openssh-client` expands runtime capability, so this is appropriate
only because the deployed Paperclip runtime explicitly needs SSH access.
## Model Used
- OpenAI Codex / `gpt-5.4`
- Tool-using agent workflow via Hermes
- Context from local repository inspection, git, and shell tooling
## 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)
- [ ] I have run tests locally and they pass
- [ ] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [ ] 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
## Thinking Path
> - Paperclip is the control plane for autonomous AI companies, and the
Docker image is the no-local-Node path for running that control plane.
> - The deploy workflow builds and pushes that image from the repository
`Dockerfile`.
> - The current image setup adds GitHub CLI through GitHub's external
apt repository and verifies a mutable keyring URL with a pinned SHA256.
> - GitHub rotated the CLI Linux package signing key, so that pinned
keyring checksum now fails before Buildx can publish the image.
> - Paperclip already has a repo-local precedent in
`docker/untrusted-review/Dockerfile`: install Debian trixie's packaged
`gh` directly from the base distribution.
> - This pull request removes the external GitHub CLI apt
keyring/repository path from the production image and installs `gh` with
the rest of the Debian packages.
> - The benefit is a simpler Docker build that no longer fails when
GitHub rotates the apt keyring file.
## What Changed
- Updated the main `Dockerfile` base stage to install `gh` from Debian
trixie's package repositories.
- Removed the mutable GitHub CLI apt keyring download, pinned checksum
verification, extra apt source, second `apt-get update`, and separate
`gh` install step.
## Verification
- `git diff --check`
- `./scripts/docker-build-test.sh` skipped because Docker is installed
but the daemon is not running on this machine.
- Confirmed `https://packages.debian.org/trixie/gh` returns HTTP 200,
matching the base image distribution package source.
## Risks
- Debian's `gh` package can lag the latest upstream GitHub CLI release.
This is acceptable for the current image contract, which requires `gh`
availability but does not document a latest-upstream version guarantee.
- A full image build still needs to run in CI because the local Docker
daemon is unavailable in this environment.
## Model Used
- OpenAI Codex, GPT-5-based coding agent. Exact backend model ID was not
exposed in this runtime; tool use and shell execution were enabled.
## 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
- [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>
- 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>
- Add USER_UID/USER_GID build args to Dockerfile
- Install gosu and remap node user/group at build time
- Set node home directory to /paperclip so agent credentials resolve correctly
- Add docker-entrypoint.sh for runtime UID/GID remapping via gosu
Co-Authored-By: Paperclip <noreply@paperclip.ing>
pnpm install needs the patches/ directory to resolve patched
dependencies (embedded-postgres). Without it, --frozen-lockfile
fails with ENOENT on the patch file.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The plugin framework landed without updating the Dockerfile. The
server now imports @paperclipai/plugin-sdk, so the deps stage needs
its package.json for install and the build stage needs to compile
it before building the server.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Switch the production stage to the built-in node user from
node:lts-trixie-slim, fixing two runtime failures:
1. Claude CLI rejects --dangerously-skip-permissions when the
process UID is 0, making the claude-local adapter unusable.
2. The server crashed at startup (EACCES) because /paperclip was
root-owned and the process could not write logs or instance data.
Changes vs the naive fix:
- Use COPY --chown=node:node instead of a separate RUN chown -R,
avoiding a duplicate image layer that would double the size of
the /app tree in the final image.
- Consolidate mkdir /paperclip + chown into the same RUN layer as
the npm global install (already runs as root) to keep layer count
minimal.
- Add USER node before CMD so the process runs unprivileged.
The VOLUME declaration comes after chown so freshly-mounted
anonymous volumes inherit the correct node:node ownership.
Fixes#344
Rewrites Dockerfile to use bookworm-slim base, installs Claude and Codex
CLIs, adds docker-compose.quickstart.yml for one-command setup, and adds
DOCKER.md with usage instructions.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
pnpm monorepo with shared packages, server, and UI workspaces.
Includes Docker multi-stage build, Postgres compose, and root TypeScript/Vitest config.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
