But only over HTTPS, to allowlisted domains, after DNS validation.

Secure HTTPS-only network access for the Hyperlight sandbox. Default-deny domain allowlist, SSRF protection, rate limiting, audit logging, and timing side-channel mitigation.

Version: 1.0.0
Host Module: host:fetch

You: /plugin enable fetch allowedDomains=api.github.com,*.example.com

Guest code:

const fetch = require('host:fetch');

// GET returns metadata only — body is read separately
const res = fetch.get('https://api.github.com/repos/deislabs/hyperlight');
if (res.error) {
    console.log('Failed:', res.error);
} else {
    // Read the body (same pattern for small or large responses)
    let body = '';
    let chunk;
    do {
        chunk = fetch.read('https://api.github.com/repos/deislabs/hyperlight');
        body += chunk.data;
    } while (!chunk.done);

    if (res.contentType === 'application/json') {
        const data = JSON.parse(body);
        console.log(data.full_name); // "deislabs/hyperlight"
    }
}

This is the most security-sensitive plugin — it opens a controlled channel between untrusted guest code and the internet. The design was reviewed by the Three Musketeers (security, architecture, and DX reviewers), resulting in 20+ security measures.

Only two fields are prompted interactively during /plugin enable (via the promptKeys feature). All others use safe defaults and can be overridden via inline config.

/plugin enable fetch allowedDomains=api.github.com
/plugin enable fetch allowedDomains=api.github.com,*.example.com allowPost=true
/plugin enable fetch allowedDomains=api.github.com maxRequestsPerMinute=10 maxResponseSizeKb=128

HTTPS GET request. Returns metadata only — the response body is cached host-side and retrieved via fetch.read(url).

• Input: URL string, optional { headers: { ... } } object
• Returns: { status, ok, contentType, totalBytes } on success, { error: string } on failure
• Note: contentLength (number) is included when the server sends a Content-Length header. The body is not included — use fetch.read(url) to read it.

Sequential body reader. Returns the next chunk of a previously fetched response.

• Input: URL string (must match a prior get() or post() call)
• Returns: { data, done } — data is a string, done is a boolean
• Note: Call in a loop until done === true. The cache is automatically purged when the last chunk is read. If the cache has expired (TTL), returns { error: "fetch error: no cached response for this URL (cache may have expired)" } — re-fetch with get().

HTTPS POST request (requires allowPost: true). Returns metadata only, same as get().

• Input: URL string, JSON-serialisable body, optional { headers: { ... } } object
• Returns: { status, ok, contentType, totalBytes } on success, { error: string } on failure
• Note: if POST is disabled, returns { error: "fetch blocked: POST not allowed" }. Use fetch.read(url) to read the response body.

Convenience function: GET + read all + parse JSON in one call.

• Input: URL string, optional { headers: { ... } } object
• Returns: Parsed JSON object directly
• Throws: Error on fetch errors, non-2xx responses (including 429), non-JSON content, or oversized responses (>512KB)
• 429 Error: Includes rate limit info in the error message: "fetchJSON: HTTP 429 (rate limited). Retry after 60s. (0/100 remaining)"

Convenience function: GET + read all binary chunks in one call.

• Input: URL string, optional { headers: { ... } } object
• Returns: Uint8Array of the response body (always — never returns an object)
• Throws: Error on fetch errors, non-2xx responses (including 429), or non-binary content type
• 429 Error: Includes rate limit info in the error message: "fetchBinary: HTTP 429 (rate limited). Retry after 60s. (0/100 remaining)"
• Note: Validates Content-Type is binary (image/*, audio/*, video/*, application/octet-stream, application/pdf, application/zip, etc.)

Errors are returned as { error: "..." } for low-level functions (get, post, read) or thrown as exceptions for convenience functions (fetchJSON, fetchBinary). The system message includes all categories so the LLM knows which are retryable and which are permanent.

Note: SSRF protection (private/internal IP blocking) is intentionally masked behind generic fetch failed: request error to avoid leaking infrastructure topology to the sandbox.

const fetch = require('host:fetch');

// --- Helper to read the full body ---
function readBody(url) {
    let body = '';
    let chunk;
    do {
        chunk = fetch.read(url);
        body += chunk.data;
    } while (!chunk.done);
    return body;
}

// Simple GET — result is metadata, body is read separately
const url = 'https://api.example.com/data';
const res = fetch.get(url);
if (res.error) {
    console.log('Error:', res.error);
} else {
    const body = readBody(url);
    if (res.contentType === 'application/json') {
        const data = JSON.parse(body);
        console.log(data);
    } else {
        console.log(body); // HTML, plain text, etc.
    }
}

// GET with headers
const authedUrl = 'https://api.example.com/me';
const authed = fetch.get(authedUrl, {
    headers: { Authorization: 'Bearer token123' },
});
if (authed.ok) {
    const profile = JSON.parse(readBody(authedUrl));
    console.log(profile);
}

// POST (if enabled)
const postUrl = 'https://api.example.com/submit';
const posted = fetch.post(
    postUrl,
    { key: 'value' },
    { headers: { 'Content-Type': 'application/json' } }
);
if (posted.ok) {
    const result = JSON.parse(readBody(postUrl));
    console.log(result);
}

You: /plugin enable fetch allowedDomains=api.github.com,*.example.com
  🔍 Auditing "fetch"...
  ⚙️  Configure "fetch":
     allowedDomains []: api.github.com, *.example.com  <-- from inline config
     Allow POST requests? [n]: n
  ℹ️  12 advanced settings using defaults. Use inline config to override.
  ✅ Plugin "fetch" enabled.

All requests are logged to ~/.hyperagent/fetch-log.jsonl (JSONL format, file mode 0600). Each entry includes:

• Timestamp, session ID, request method, URL, domain
• Whether the request was allowed or blocked
• Response status code and body size (if allowed)
• Error message (if blocked)

The log auto-rotates at 5000 entries, keeping the newest half. Rotation is throttled to every 50 writes to avoid I/O overhead.