docs: improve agents, architecture, webhooks, and HTTP proxy pages - #94
Merged
Conversation
✅ Deploy Preview for decap-documentation ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
- Rewrite concepts/agents.mdx with deployment section (Docker, Helm, system service), cleaner Standard/Embedded mode docs, consolidated key management commands, and Mintlify component fixes - Expand setup/architecture.mdx with component details, ports table, session flow walkthrough, deployment topologies, and auth overview - Reorganize setup/apis/webhooks-siem.mdx to lead with Runbook Hooks (recommended approach) and move Svix content under a deprecation notice - Improve quickstart/web-applications/http-proxy.mdx with tabbed setup (CLI/Web App/API), accessing via native client, custom headers, and self-signed cert docs - Add note to webapps-and-apis.mdx linking to HTTP Proxy as the underlying connection type - Add integrations/siem.mdx and register it in docs.json nav Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
nsaronson
force-pushed
the
docs/improve-agents-architecture-webhooks
branch
from
February 26, 2026 18:59
a71359a to
a0cb422
Compare
mtmr0x
requested changes
Feb 26, 2026
Comment on lines
192
to
210
| <Note> | ||
| To obtain a valid token for `hoop run`, navigate to the web application and create a connection. This will display the correct key. | ||
| </Note> | ||
|
|
||
| </aside> | ||
| ### Organization Keys | ||
|
|
||
| ### Get the Key | ||
| An organization key connects multiple agents using a single key. It only works with `hoop run`, and one key is available per organization (self-provisioned by default). | ||
|
|
||
| ```bash | ||
| # Get | ||
| hoop admin get orgkeys | ||
| ``` | ||
|
|
||
| ### Revoke the Key | ||
| # Create | ||
| hoop admin create orgkeys | ||
|
|
||
| ```bash | ||
| # Revoke | ||
| hoop admin delete orgkeys | ||
| ``` | ||
|
|
Member
There was a problem hiding this comment.
you can remove all reference for hoop run from the docs, we deprecated it long ago and never removed. Great opportunity for it
Comment on lines
+96
to
+103
| Create the connection, pointing it at your internal service: | ||
|
|
||
| ```bash | ||
| hoop admin create connection my-api \ | ||
| -a default \ | ||
| -t application/httpproxy \ | ||
| -e REMOTE_URL=https://internal-api.example.com | ||
| ``` |
Member
There was a problem hiding this comment.
we are removing and deprecating any instructions that is not agent for the docs. Anything related to resources/connections shouldn't be instructed via CLI
Comment on lines
+160
to
+167
| ```bash | ||
| hoop admin create connection my-api \ | ||
| -a default \ | ||
| -t application/httpproxy \ | ||
| -e REMOTE_URL=https://internal-api.example.com \ | ||
| -e HEADER_AUTHORIZATION="Bearer <token>" \ | ||
| -e HEADER_X_API_KEY="<api-key>" | ||
| ``` |
Member
There was a problem hiding this comment.
same here regarding using CLI as instruction
Comment on lines
+174
to
+179
| hoop admin create connection my-api \ | ||
| -a default \ | ||
| -t application/httpproxy \ | ||
| -e REMOTE_URL=https://internal-api.example.com \ | ||
| -e INSECURE=true | ||
| ``` |
Comment on lines
+28
to
+36
| hoop admin create plugin runbooks --overwrite \ | ||
| -c GIT_URL=git@github.com:your-org/your-repo.git \ | ||
| -c GIT_SSH_KEY=file://$HOME/.ssh/your_key \ | ||
| -c GIT_HOOK_CONFIG_TTL=120 | ||
| ``` | ||
|
|
||
| <Tip> | ||
| Use a higher TTL if your hook scripts change infrequently — this reduces the number of requests to your git server. | ||
| </Tip> |
| To view any activity, interact with any connection. | ||
|
|
||
| Accessing the **Message Logs** link in the dashboard will display the `hoop connect` event. | ||
| To view activity, interact with any connection. The **Message Logs** link shows `hoop connect` events. |
Member
There was a problem hiding this comment.
I'd remove this hoop connect events and say it shows native connections events or if it shows all, say it shows all connections events
|
|
||
| 1. **Authentication** — the user authenticates via your identity provider (OIDC, SAML, or local auth). The gateway verifies the token and loads the user's identity and group membership. | ||
|
|
||
| 2. **Authorization** — the gateway checks whether the user has access to the requested connection, based on access control rules and the connection's configured access mode (`exec`, `connect`, or `runbooks`). |
Member
There was a problem hiding this comment.
Suggested change
| 2. **Authorization** — the gateway checks whether the user has access to the requested connection, based on access control rules and the connection's configured access mode (`exec`, `connect`, or `runbooks`). | |
| 2. **Authorization** — the gateway checks whether the user has access to the requested connection, based on access control rules and the connection's configured access mode |
- Remove all hoop run references from agents.mdx (Embedded Mode section, Warning, Note, and Organization Keys subsection — all deprecated) - Remove CLI tab from http-proxy.mdx Setup section; replace CLI-only code blocks in Custom Headers and Self-Signed Certificates with API secret object examples - Replace hoop admin create plugin runbooks CLI block in webhooks-siem.mdx with a prose reference to the Runbooks configuration guide - Replace "hoop connect events" with "all connection events" in webhooks-siem.mdx - Apply suggested text for Authorization step in architecture.mdx Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Deploying section now says to generate the key in the UI or via the API, with the DSN format shown as an example - Removed Authentication Keys section (DSN field breakdown table) - Removed Key Management / Agent Keys section (CLI-based key commands) - Removed embedded mode mention from page intro Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Contributor
Author
|
mtmr0x
approved these changes
Feb 27, 2026
mtmr0x
left a comment
mtmr0x
left a comment
Member
There was a problem hiding this comment.
There was one information missing, I added it as a suggestion so you can click and add it and I'm approving so you don't get blocked by it waiting for an approve on such minor detail
Co-authored-by: Mat <github@mat-m.com>
This was referenced Jul 30, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
concepts/agents.mdx) — new deployment section covering Docker Compose, Kubernetes Helm, and Linux/macOS system service; updated HOOP_KEY intro to point to the web app / API instead of CLI; removed Embedded Mode, Authentication Keys, and Key Management sections; replaced legacy<aside>tags with Mintlify componentssetup/architecture.mdx) — expanded from a sparse component list into a full page covering component details, ports table, session flow walkthrough, deployment topologies, and authentication overviewsetup/apis/webhooks-siem.mdx) — reorganized to lead with Runbook Hooks as the recommended approach; Svix content moved below a deprecation warning; replaced CLI plugin setup command with prose reference to the Runbooks configuration guide; replaced "hoop connect events" with "all connection events"quickstart/web-applications/http-proxy.mdx) — tabbed Setup section (Web App / API), native client access documentation, custom headers and self-signed cert docs use API secret object examples instead of CLIquickstart/web-applications/webapps-and-apis.mdx) — added note linking to HTTP Proxy as the underlying connection typeintegrations/siem.mdx) — new top-level integrations page linking through to the Webhooks/SIEM setup page; registered indocs.jsonTest plan
npm run devand verify all edited pages render correctly at localhost:3000integrations/siempage appears in the sidebar🤖 Generated with Claude Code