octet

Documentation Extensions

Web search

Retrieve bounded public web evidence.

Distribution: 0.8.0. This bundle requires exactly octet 0.8.0. Use the version-matched installation and the 0.8.0 release record for signed assets and public-install evidence. Reviewed source checkouts and local archives remain separate installation options.

Search the public web and retrieve pages with stable citations. Choose Brave Search or a configured SearXNG JSON endpoint. This extension does not open browser tabs, sign in, run JavaScript, or submit forms.

With octet 0.8.0, Python 3.9+ available as python3, and verified matching published assets, the catalog path is:

console
octet extension install octet-web-search
octet --enable-extension octet-web-search

For a reviewed source checkout instead, add --extension-dir ./extensions to the launch command from the repository root.

Then choose a provider and load the optional research skill:

text
/web-search setup brave
/web-search status
/skills load octet-web-search

Brave setup shows https://api.search.brave.com/app/keys and asks for the key through a private input surface. Do not paste a key into a prompt or ordinary configuration. For example, ask: “Find the official Python pathlib documentation and cite the sources for your summary.”

Use /web-search setup searxng instead for SearXNG; its instance must allow format=json. /extensions also provides the provider picker. Selecting the already enabled extension lets you switch providers or disable it; /web-search logout is the scriptable logout command.

What the tools do#

Tool Use Hard limits
web_search Search using the selected provider. 512-byte query, 5 requested domains, 10 results, 20 seconds, 512 KiB provider response.
web_fetch Retrieve one public HTML/XHTML/plain-text page. HTTP(S) ports 80/443, 20 seconds, 3 redirects, 512 KiB download, 128 KiB normalized content.
web_find Find a literal pattern and return excerpts. 256-byte pattern, 20 matches, 512-byte excerpts; the same fetch limits.

Configuration and call arguments can reduce limits, never exceed them. Cite the returned [web-…] IDs: they are derived from sanitized URLs, not result rank or cache state. Text results are marked UNTRUSTED WEB DATA; their content cannot grant permission or change policy.

Privacy and configuration#

Queries and selected domain filters go to your search provider. Fetch/find sends the sanitized URL to the public origin, with normal DNS and TLS traffic. Queries and retrieved content remain in ordinary tool arguments/results, not compact status or activity labels. The cache is bounded, process-local, and never saved to disk.

Brave credentials live in the owner-private regular file ~/.octet/credentials/octet-web-search-brave.key; they are not included in URLs, results, diagnostics, or frontend state. Credentialed requests never redirect; 401/403 invalidates the stored key so setup/search can ask again.

SearXNG settings live at ~/.config/octet/octet-web-search.json. The provider picker preserves them while Brave is selected. Endpoint URLs must be non-secret; configured query parameters such as timeout_limit are retained and the search request adds its own query, JSON, and safe-search parameters. A private self-hosted provider requires allow_private_endpoint: true; this exception never permits private web_fetch/web_find destinations or redirects. limits.allowed_domains is an egress allowlist; a tool's domains can only narrow it. See the complete configuration rules.

Activation and reference#

Installation is inert; the bundle stays disabled until explicitly enabled. Default full access (unsafe_host) trusts the selected extension implicitly without saving a grant. --trust-extension and source-bound trusted_extensions grants are optional, never activation. --safe-mode removes implicit trust and keeps the process stopped even with explicit grants: executable startup still requires unsafe_host. An admitted extension has your OS authority; manifest consent metadata is not a sandbox. Skill loading remains independent.

The source bundle 0.8.0 requires exactly octet 0.8.0 and uses API 0.4. The following is a bundled-runtime reference, not a general SDK authoring tutorial.