octet

Documentation Extensions

Web search

Retrieve bounded public web evidence.

Manual for v0.9.5. Stable release: v0.9.5.

Source candidate distribution: 0.9.5. This bundle needs exactly octet 0.9.5. Use the version-matched installation and the 0.9.5 candidate record for availability and remaining qualification. 0.9.5 assets are not published; use the reviewed source-checkout route below until publication is approved.

Search the public web and retrieve pages with stable citations. Pick Brave Search or a configured SearXNG JSON endpoint. It doesn't open browser tabs, sign in, run JavaScript or submit forms.

After approved 0.9.5 publication and verification of matching assets, the catalog path needs octet 0.9.5 and Python 3.9+ as python3:

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

For this unpublished candidate, launch the reviewed source-built host from the repository root instead (see build from a checkout):

console
./target/release/octet --safe-mode --extension-dir ./extensions \
    --enable-extension octet-web-search

Then open /extensions, choose octet-web-search (choosing a disabled extension enables it first), and pick Use Brave Search. Load the optional research skill with /skills load octet-web-search.

Brave setup shows https://api.search.brave.com/app/keys and asks for the key through a private input. Don't paste a key into a prompt or ordinary config. Then ask something like: "Find the official Python pathlib documentation and cite the sources for your summary."

Pick Use SearXNG instead for SearXNG. Its instance must allow format=json, and Change the SearXNG endpoint points it elsewhere later. The same menu shows the current provider, checks its status, logs out of Brave Search (deleting the stored key) and disables the extension. The web UI has no options menu yet. There the same actions run as the /web-search command (status, setup brave, setup searxng, endpoint, logout).

What the tools do#

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

Config and call arguments can lower the limits, never raise them. The max_bytes tool argument limits normalized output, not the HTTP download. Existing configs with a smaller limits.max_download_bytes keep that lower cap until updated. Cite the returned [web-…] IDs. They come from sanitized URLs, not result rank or cache state. Text results are marked UNTRUSTED WEB DATA, and their content can't grant permission or change policy.

Privacy and configuration#

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

Brave credentials live in the owner-private file ~/.octet/credentials/octet-web-search-brave.key. They never appear in URLs, results, diagnostics or frontend state. Credentialed requests never redirect, and a 401 or 403 invalidates the stored key so setup or search can ask again.

SearXNG settings live in ~/.config/octet/octet-web-search.json, and the provider picker keeps them while Brave is selected. Endpoint URLs must be non-secret. Configured query parameters such as timeout_limit are kept, and the search request adds its own query, JSON and safe-search parameters. A private self-hosted provider needs allow_private_endpoint: true, and that never allows private web_fetch or web_find destinations or redirects. limits.allowed_domains is an egress allowlist, and a tool's domains can only narrow it. See the full configuration rules.

Activation and reference#

Installing is inert, and the bundle stays disabled until you enable it. Default full access (unsafe_host) trusts the selected extension implicitly, without saving a grant. --safe-mode removes implicit trust, but an enabled extension with a grant for its selected source can start. --trust-extension and source-bound trusted_extensions grants never enable it; an explicit --extension-dir is an invocation-only authority grant, also not activation. A bare persistent name grants only the global bundle, never a same-named project shadow. --no-process/--no-shell, workspace trust, and source, compatibility and integrity checks still apply. Granted code runs with your OS authority outside the tool-effect broker; safe mode governs brokered effects, not OS isolation. Manifest consent metadata isn't a sandbox. Skill loading is independent.

The source bundle 0.9.5 needs exactly octet 0.9.5. For a reviewed source checkout, select it with --extension-dir ./extensions. What follows is a bundled-runtime reference, not a general SDK authoring tutorial.