mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-15 12:28:10 +02:00
DottaandPaperclip
5a9ce11c49
Copy the immutable target JSON into the existing isolated helper fixture without changing negative assertions. Synchronize environment qualification recipes and access limits under the updated map contract. Co-Authored-By: Paperclip <noreply@paperclip.ing>
85 lines
5.3 KiB
Markdown
85 lines
5.3 KiB
Markdown
# Local, SSH, and sandbox environments
|
|
|
|
Operators configure where agents execute, probe readiness, select an environment for work, and inspect remote provisioning or custom-image state when the installed provider supports it.
|
|
|
|
Implementation: [environment settings](../../ui/src/pages/CompanyEnvironments.tsx), [environment runtime](../../server/src/services/environment-runtime.ts).
|
|
|
|
Agent access: [companion](../agent-access-map/execution-environments.md).
|
|
|
|
## Sub-features
|
|
|
|
- `configuration`: inspect local environments and configure available SSH/sandbox targets.
|
|
- `capabilities`: select only drivers/providers that advertise the required execution capability.
|
|
- `probe`: test reachability and runtime prerequisites in the actual target.
|
|
- `assignment`: bind the intended agent/project/workspace to its execution target.
|
|
- `images`: inspect supported sandbox custom-image preparation and terminal workflows.
|
|
|
|
## How to get to it (user POV)
|
|
|
|
### `environment-settings`
|
|
|
|
Open Settings → Environments, then create/edit a supported target.
|
|
The canonical URL is `/company/settings/instance/environments`. Enable
|
|
`enableEnvironments` first; keep `enableManagedSandboxOnly` off to inspect local
|
|
targets. The catalog is instance-scoped and mutation requires a local operator
|
|
or instance administrator.
|
|
|
|
### `remote-execution`
|
|
|
|
Choose the environment in agent/project/workspace configuration, then inspect the resulting task/run and workspace.
|
|
|
|
## Driving it with Playwright and the Paperclip CLI
|
|
|
|
Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Use an owned disposable target and a supported provider plugin. Record provider, target identity, account, and spending constraints before a live remote run.
|
|
|
|
### `environment-settings`
|
|
|
|
Automated: [environment UI](../../ui/src/pages/CompanyEnvironments.test.tsx), [driver configuration UI](../../ui/src/pages/CompanySettings.test.tsx), and [environment service](../../server/src/__tests__/environment-service.test.ts) cover configuration behavior.
|
|
|
|
Manual: Save a disposable target, reload it, and run its available probe. Verify both success and missing-credential/reachability errors identify the target. Confirm unavailable providers are not offered as working run targets.
|
|
|
|
For an immutable sandbox image, pin the OCI image with `@sha256` and explicitly
|
|
probe the saved environment in the intended company. The existing connection
|
|
probe allocates a fresh lease and can measure its OS, architecture and libc.
|
|
Qualification is recorded only when the selected image/configuration matches
|
|
the live lease and cleanup is confirmed. Inspect `platformQualificationRecorded`
|
|
and its diagnostic in the probe result: connection success alone does not mean
|
|
the image has native runtime qualification.
|
|
|
|
The measured record is server-owned, company-bound and tied to the effective
|
|
configuration and active custom-image identity. Mutable tags, provider defaults
|
|
and name-only snapshots do not qualify. Changing the target or image invalidates
|
|
the record; normal metadata edits cannot forge or overwrite it, and API reads
|
|
omit the private metadata. Reading this evidence for discovery or creation does
|
|
not allocate a sandbox. The draft `probe-config` checks are not a saved-image
|
|
qualification operation. See the [runtime contract](../../packages/paperclip-runner/README.md)
|
|
and [adapter validation recipe](./runs-adapters.md#adapter-setup) for native
|
|
binary/provider readiness after platform qualification.
|
|
|
|
Verification recipe: probe a pinned owned image, record its company/config/image
|
|
identity and cleanup result, then change the image or target and verify its old
|
|
qualification is not reused. A mutable-image connection can succeed while
|
|
qualification remains absent. Assert ordinary agent and non-admin board probe
|
|
requests are denied, and environment create/PATCH payloads cannot supply
|
|
qualification metadata.
|
|
This recipe and its [probe controls](../../server/src/__tests__/environment-probe.test.ts)
|
|
are not claims that a live provider or agent-access journey ran for this map update.
|
|
|
|
The local row has no UI Test button. Its API/CLI probe reports host/cwd
|
|
availability only; it does not validate an adapter binary, workspace, or task
|
|
execution. Remote-driver probes and a real bounded run need their own evidence.
|
|
|
|
### `remote-execution`
|
|
|
|
Automated: [execution target](../../server/src/__tests__/environment-execution-target.test.ts) and [custom images](../../server/src/__tests__/environment-custom-images-service.test.ts) cover contracts; [SSH live test](../../server/src/__tests__/environment-live-ssh.test.ts) requires its own external setup.
|
|
|
|
Manual: Run a bounded command in the intended target, inspect its output and workspace, and verify execution did not silently fall back to the server host. For custom-image changes, build/probe the disposable image before assigning it. Inspect cleanup and shutdown after the run.
|
|
|
|
## Gotchas
|
|
|
|
- A probe is narrower evidence than a complete task with tools, files, and resumption.
|
|
- Platform qualification does not authenticate a model account or qualify every
|
|
harness; the selected native runtime still needs its own setup and useful-task proof.
|
|
- The local option may appear only when editing an existing local environment; availability follows current UI/provider capabilities.
|
|
- Workspace service reachability and environment reachability are separate checks.
|