Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-08 00:54:38 +02:00
Code Issues Packages Projects Releases Wiki Activity
4,192 Commits 1,100 Branches 1,788 Tags
5da649986016e4010da8156f83f5bfc9c0128be4
Commit Graph
3 Commits
Author SHA1 Message Date
Neeraj Kumar Singh BandNeeraj Kumar Singh d5ceb82571 Prefer loopback runtime API URL for local agents (#5102) 
## Thinking Path

> - Paperclip is the open-source app that manages AI agents and their
work coordination
> - The server subsystem exposes a control-plane HTTP API that agents
read and write task state against at runtime
> - On local development machines, Paperclip binds to loopback
(`127.0.0.1:3100`) but also advertises LAN hostnames via
`allowedHostnames` for multi-device setups
> - Agents inherit their API URL from `PAPERCLIP_API_URL` /
`PAPERCLIP_RUNTIME_API_URL` env vars exported during server startup
> - `choosePrimaryRuntimeApiUrl` was selecting the first entry in
`allowedHostnames` (the LAN IP) before the loopback bind host, so agents
on the same machine tried to connect to an unreachable LAN address
(NEE-327)
> - This PR fixes the chooser to return the normalized loopback bind
host first, before considering LAN `allowedHostnames`
> - The benefit is that local agents reliably reach the control plane
regardless of `allowedHostnames` configuration

## What's going on

Local Paperclip agents were sometimes inheriting
`PAPERCLIP_API_URL=http://192.168.1.50:3100` even when the server was
bound to loopback, which made the control plane unreachable from this
workspace. This keeps the runtime API on the loopback bind host for
local startup while still preserving LAN candidates for other callers.

## Problem

`choosePrimaryRuntimeApiUrl` preferred the first allowed hostname over
the actual loopback bind host. In the failing setup from NEE-327, that
exported `http://192.168.1.50:3100` into agent env even though
`http://127.0.0.1:3100` was the reachable control-plane URL.

## Solution

The primary runtime URL chooser now returns the normalized loopback bind
host before considering `allowedHostnames`. I added a focused unit test
for the chooser and a startup regression that verifies
`PAPERCLIP_RUNTIME_API_URL` / `PAPERCLIP_API_URL` stay on `127.0.0.1`
while the candidate list still includes the LAN hostname.

## Testing

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/runtime-api.test.ts
src/__tests__/server-startup-feedback-export.test.ts`
- Result: `2` files passed, `13` tests passed
- Runtime check: `curl -sS http://127.0.0.1:3100/api/health` returned
`{"status":"ok",...}` during this heartbeat

## Notes

Already-running local Paperclip servers need a restart to export the
corrected `PAPERCLIP_API_URL` into new agent runs. Rollback is revert
`df8d7fcf`.

## Model Used

Claude Sonnet 4.6 (`claude-sonnet-4-6`), 1M context window, via the
Paperclip Founding Engineer agent harness. Capabilities used: extended
tool use, code editing, test execution, shell commands.

## 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 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
- [ ] 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: Neeraj Kumar Singh <b.nirajkumarsingh@hotmail.com>
 2026-06-20 14:03:21 -07:00
Devin Foley 367d4cab72 Fix SSH callback URL selection for LAN and private networks (#4799) 
## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies
> - Agents can run on remote hosts via SSH environments
> - When a remote agent needs to call back to the Paperclip API, it
needs a reachable URL
> - But the runtime API URL candidate builder did not account for
private network topologies where the server is only reachable via LAN or
VPN addresses
> - Agents on SSH hosts were failing to connect because the callback URL
pointed to localhost or an unreachable address
> - This PR fixes callback URL selection to honor `PAPERCLIP_API_URL`,
prefer LAN-reachable candidates, filter unreachable link-local
addresses, and include interface hosts in onboarding invite URLs
> - The benefit is SSH-based agents can reliably reach the Paperclip API
on private networks without manual URL configuration

## What Changed

- `runtime-api.ts`: Added `PAPERCLIP_API_URL` as a first-priority
candidate in `buildRuntimeApiCandidateUrls`; extracted
`collectReachableInterfaceHosts` to enumerate non-loopback,
non-link-local network interface IPs with IPv4 preference
- `server/src/index.ts`: Export `PAPERCLIP_API_URL` from the server
environment so it is available to callback candidate resolution
- `server/src/routes/access.ts`: Include LAN interface hosts in
onboarding invite connection candidates
- `server/src/config.ts`: Attempted auto-allowing LAN interface hosts,
then reverted to the per-instance allowlist approach (both commits
included for history clarity)

## Verification

- `pnpm test` — all existing and new tests pass, including new tests for
LAN candidate ordering and link-local filtering
- `pnpm typecheck` — clean
- Manual: start a Paperclip server on a machine with a LAN IP, create an
SSH environment pointing to another host on the same LAN, verify the
agent's callback URL uses the LAN IP rather than localhost

## Risks

- Low-medium. The candidate list now includes more addresses (all
non-loopback LAN interfaces). These are candidates for the agent to try,
not an allowlist — the server's allowed hostnames still gate which
origins are accepted. Ordering change (LAN preferred over loopback)
could affect existing setups where localhost was intentionally
preferred.

## Model Used

Codex GPT 5.4 high via Paperclip.

## 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
 2026-04-29 15:56:17 -07:00
Devin Foley 70679a3321 Add sandbox environment support (#4415) 
## 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
 2026-04-24 12:15:53 -07:00