mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-10 03:51:29 -10:00
c65bc9a9bf
Brings **paperclip-docs** in line with paperclip **v2026.916.0**, shipping the `v2026.831.1 → v2026.916.0` cycle drafted on `nightly`, stamped to the release tag, with a documentation changelog entry. This branch was cut from `nightly` **after** merging `origin/main` into it, so it sits on top of the operator-first connectors catalog (#124) rather than reverting it. ## Manifest **New pages (4)** - `docs/reference/api/connection-intents.md` — Connection Intents API - `docs/reference/cli/connections.md` — `connections` command - `docs/reference/cli/managed-agent.md` — `managed-agent` command - `docs/reference/cli/test-drive.md` — `test-drive` command **Updated pages (17)** - Roles & Permissions + Company Administration — `tools:*` role-default changes - Connect an Agent to GitHub — managed GitHub connection (Connectors), Option C - Agents API — Managed/Remote Agent Profiles, `***REDACTED***` env serialization - Tool Gateway API — agent self-authorization (`start-authorization`, `token`) - Instance Admin API — instance-settings + task-drain routes - Plugin SDK — `ctx.access` + `ctx.authorization` clients, login-PTY/duplex streaming - Environment Variables — Paperclip ID Connector block + HTTP adapter allowlist var - Adapters: Codex (`gpt-5.6-sol` default, Fast mode, auth cache), Claude Code (Fable 5.1 + CLI floor), Grok Local (SuperGrok subscription auth), HTTP (SSRF guard), Sandbox Providers (Daytona warm runner), OpenCode (model pre-flight) - CLI: `adapter detect-model`, `onboard` tool-action signing secret - Command palette — recent tasks in sidebar - `docs/reference/changelog.md` — new `v2026.916.0` accordion entry All 21 touched pages stamped `paperclip_version: v2026.916.0`. ## Verification **Tag-accuracy gate (Phase 5.7)** — `check-tag-accuracy.mjs --tag v2026.916.0 --base main --head nightly` flagged 5 pages, **every one verified present in the code at the release tag** and cleared as known `verify-edit` false-positive classes. No content was quarantined; **no post-tag leaks**: | Page | Flagged claim(s) | Verified at tag | |---|---|---| | `cli/connections.md` | `PAPERCLIP_RUNTIME_TOOLS_*` (3) | present in `cli/src/commands/client/connections.ts` (runtime-injected env) | | `cli/managed-agent.md` | `--profile-key`, `--api-key-secret-id` | present in `cli/src/commands/managed-agent.ts` (`.requiredOption`/`.option`) | | `cli/test-drive.md` | `--harness` | present in `cli/src/commands/test-drive.ts` (`new Option`) | | `deploy/environment-variables.md` | `PAPERCLIP_ID_CONNECTOR_*` (5) | present in `.env.example` at tag | | `plugins/sdk.md` | `PLUGIN_*` (6) | present in `packages/plugins/sdk/src/index.ts` (exported constants) | Rationale: nightly's drafts were authored from parent `af8439a`, **226 commits inside the tag**, so they document in-tag surfaces by construction. ### ⚠ Drift `check-drift.mjs --against v2026.916.0` returned 14 records — **all verified present at the tag** (checker false positives), listed here for the reviewer to confirm: - **env-var (9, high-confidence in the tool, verified present):** `PAPERCLIP_WORKSPACE_GIT_SCAN_{CONCURRENCY,QUEUE_CAPACITY,TIMEOUT_MS,CACHE_TTL_MS}` and `PAPERCLIP_ID_CONNECTOR_{BASE_URL,ENVIRONMENT,INSTANCE_ID,SIGN_PRIVATE_KEY,SEAL_PRIVATE_KEY}` — all present in `.env.example` at the tag; the drift scanner's scoped file scan missed them. - **Verify: rest-route (5, medium-confidence):** `POST/PUT/GET /api/companies/import/transfers*` — present at the tag in `server/src/routes/companies.ts`, registered via the `COMPANY_IMPORT_TRANSFERS_ROUTE_PATH` prefix constant (the documented prefix/dynamic-registration blind spot). ### ⚠ Verification Failures None. All tag-accuracy and drift flags above were verified present at the tag. ### ↻ Renames detected None. The connectors catalog (`docs/connectors/**`) arrived via the `main` merge (#124), not as a renamed surface; no new top-level draft directories were introduced this cycle. ## Screenshots **238 of 342 screenshots** flagged stale across 50 routes (see `SCREENSHOTS_PENDING.md`). This is a wide 16-day window touching ~921 UI files, so most are dependency-touch flags rather than confirmed visual changes. Recommend `npm run screenshots:refresh` on this release branch as a dedicated follow-up before merge; PNGs go to a separate PR for human review. ## Build gates (all green on this branch) - `npm run docs:build` — 257 pages - `npm run docs:test` — SEO metadata, crawlable-links (71,749 links resolve), doc-link-resolution, skill-source-blocks, static-routes, hierarchical-nav ## Post-merge checklist (Phase 9 — do NOT skip) - [ ] Squash-merge this PR (repo is squash-only) - [ ] `git checkout main && git pull` - [ ] `git tag docs/v2026.916.0 && git push --tags` - [ ] `node scripts/sync/realign-nightly.mjs release/v2026.916.0 --push` (restore ancestry; keep nightly post-tag drafts) - [ ] Flip `nightly` `.sync-state.json` back to `"branch_mode": "nightly"` (leave `base_release_tag` at `v2026.916.0`) - [ ] Verify `docs.paperclip.ing` serves the release: a new page (`/reference/cli/test-drive/`), a changed page, and the changelog top entry reads `Docs for v2026.916.0` - [ ] If production is stale, republish: `npm run docs:build && npx wrangler pages deploy .site --project-name paperclip-docs --branch main` 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]> Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> Co-authored-by: Dotta <[email protected]> Co-authored-by: ClaudeCoder <[email protected]>
86 lines
5.2 KiB
Markdown
86 lines
5.2 KiB
Markdown
---
|
|
paperclip_version: v2026.916.0
|
|
seo_title: The managed-agent Command
|
|
seo_description: Provision and qualify a locked-down Anthropic managed agent and environment, then save the company profile Paperclip uses to run it.
|
|
---
|
|
|
|
# Managed Agent Command
|
|
|
|
`managed-agent` provisions the remote, provider-hosted runtime a company can use in place of a locally executed adapter. Today it targets Anthropic's Managed Agents beta: it creates (or adopts) a locked-down Agent and Environment on Anthropic's side, checks that both match Paperclip's strict no-network, no-tools safety profile, and then stores a **managed-agent profile** on your company that the runtime reads when it dispatches work.
|
|
|
|
```sh
|
|
paperclipai managed-agent setup --company-id <company-id> \
|
|
--profile-key <key> \
|
|
--display-name "<name>" \
|
|
--api-key-secret-id <uuid>
|
|
```
|
|
|
|
This is a board-operator, one-time provisioning task, not something you run per heartbeat. You set a company up once so its agents can run on the managed provider; after that the runtime does the dispatching.
|
|
|
|
> **Note:** The command reads `ANTHROPIC_API_KEY` from the CLI process environment to talk to Anthropic directly. Export a valid key before you run it, or the command stops before doing anything.
|
|
|
|
---
|
|
|
|
## `managed-agent setup`
|
|
|
|
`setup` is the only subcommand. It creates or adopts a locked-down Anthropic Agent and Environment, verifies them, and stores the resulting company profile.
|
|
|
|
Under the hood it either finds existing Anthropic resources tagged with your `--profile-key` (or the explicit ids you pass) or creates new ones with a fixed safety posture: an Environment with limited networking, no allowed hosts, and no installed packages, and an Agent with no tools, no MCP servers, no skills, and no multi-agent config. If anything you adopt does not match that posture, `setup` refuses it rather than trusting it.
|
|
|
|
```sh
|
|
# Provision from scratch, acknowledging the beta's retention terms
|
|
paperclipai managed-agent setup --company-id <company-id> \
|
|
--profile-key acme-prod \
|
|
--display-name "Acme Production" \
|
|
--api-key-secret-id 6f1c2e3a-1b2c-4d5e-8f90-0a1b2c3d4e5f \
|
|
--acknowledge-retention
|
|
|
|
# Adopt an Anthropic Agent and Environment you already created
|
|
paperclipai managed-agent setup --company-id <company-id> \
|
|
--profile-key acme-prod \
|
|
--display-name "Acme Production" \
|
|
--api-key-secret-id 6f1c2e3a-1b2c-4d5e-8f90-0a1b2c3d4e5f \
|
|
--agent-id <anthropic-agent-id> \
|
|
--environment-id <anthropic-environment-id> \
|
|
--acknowledge-retention
|
|
```
|
|
|
|
### Required options
|
|
|
|
| Flag | Use |
|
|
|---|---|
|
|
| `--profile-key <key>` | **Required.** Stable company profile key. It also tags the Anthropic resources so `setup` can find them again on a later run. |
|
|
| `--display-name <name>` | **Required.** Human-readable profile display name, also used to name the Anthropic Agent and Environment. |
|
|
| `--api-key-secret-id <id>` | **Required.** The id of an existing company secret that holds `ANTHROPIC_API_KEY`. Must be a UUID. |
|
|
|
|
### Optional options
|
|
|
|
| Flag | Default | Use |
|
|
|---|---|---|
|
|
| `--model <id>` | `claude-sonnet-5` | The pinned Claude model. It must be the qualified Managed Agents model, `claude-sonnet-5`. |
|
|
| `--max-session-list-cost-usd <usd>` | `1.00` | Default hard session cost ceiling. Must resolve to at least one cent. |
|
|
| `--agent-id <id>` | _(unset)_ | Adopt an existing Anthropic Agent instead of creating one. |
|
|
| `--agent-version <version>` | _(unset)_ | Pin a specific existing Agent version. |
|
|
| `--environment-id <id>` | _(unset)_ | Adopt an existing Anthropic Environment instead of creating one. |
|
|
| `--probe` | `false` | Read-only qualification. Verifies (or discovers) resources and prints the profile it *would* store, without creating or persisting anything. |
|
|
| `--acknowledge-retention` | `false` | **Required to actually provision.** Acknowledges the beta's data-retention terms and its non-ZDR, non-HIPAA status. |
|
|
|
|
`setup` also accepts the standard client options and is company-scoped: `-C, --company-id <id>` is required (from the flag or your context profile), because the finished profile is stored against that company. See [Common Options](./common-options.md).
|
|
|
|
> **Tip:** Run with `--probe` first. It exercises the whole discovery-and-verification path and shows you the exact profile that would be saved, so you can confirm the model, ceiling, and adopted resources before you commit them with a real run.
|
|
|
|
---
|
|
|
|
## What gets stored
|
|
|
|
On a real (non-probe) run, `setup` stores a profile on the company that records the profile key and display name, the resolved Anthropic Agent id and pinned version, the Environment id, the default model and session cost ceiling, the id of the secret holding the key, and a qualification stamp describing the safety posture that was verified. With `--probe`, that same profile is printed instead of saved.
|
|
|
|
---
|
|
|
|
## See also
|
|
|
|
- [Secrets Commands](./secrets.md) — create the company secret whose id you pass as `--api-key-secret-id`.
|
|
- [Adapter Commands](./adapter.md) — the locally executed adapters this managed provider stands alongside.
|
|
- [Agent Commands](./agent.md) — the agents that run against the profile once it is provisioned.
|
|
- [Common Options](./common-options.md) — shared client flags and company resolution.
|