olegselajev241/exa-sbx-kit:latest

schemaVersion: "3"
displayName: Exa Search
author: Oleg Šelajev <[email protected]>
description: Wires hosted Exa MCP into sandboxed agents. Uses free access without a key, or authenticated access through optional host-side key injection.
sourceUrl: https://github.com/shelajev/exa-sbx-kit
version: 2.0.1
licenses:
    - MIT
kind: mixin
provides:
    - exa-search
capabilities:
    - type: com.docker.sandbox/network-policy@2
      config:
        runtime:
            allow:
                - mcp.exa.ai
    - type: com.docker.sandbox/credential@1
      optional: true
      config:
        apiKey:
            inject:
                - domain: mcp.exa.ai
                  format: '%s'
                  header: x-api-key
            proxyManaged: true
        phase: runtime
        service: exa
      description: Optional authenticated access to hosted Exa MCP
    - type: com.docker.sandbox/lifecycle@1
      config:
        startup:
            - command:
                - exa-node
                - /usr/local/libexec/exa-configure-mcp.cjs
              description: Wire hosted Exa MCP into project, VS Code, and Gemini agent configs (idempotent)
              user: "1000"
            - command:
                - sh
                - -c
                - if command -v codex >/dev/null 2>&1; then if codex mcp get exa >/dev/null 2>&1; then codex mcp remove exa || exit; fi; codex mcp add exa --url https://mcp.exa.ai/mcp; fi
              description: Wire hosted Exa MCP into Codex (idempotent)
              env:
                - CODEX_HOME
              user: "1000"
    - type: com.docker.sandbox/agent-context@1
      config:
        content: |
            Exa web search is available through hosted MCP at https://mcp.exa.ai/mcp, wired into this agent's config.
            - For questions needing current web information, search with Exa before saying you cannot.
            - Search and page fetching work without a key, subject to free rate limits. agent_run research requires an authenticated Exa account.
            - If a host Exa key is configured, the sandbox proxy injects x-api-key on requests. No key or sentinel is stored in agent configuration. For authenticated access or higher limits, run `sbx secret set -g exa` on the host and restart the sandbox. An invalid configured key must be corrected; it is not silently ignored.
            - The kit packages its own Node.js runtime; the workload must provide glibc 2.36 or newer (Debian 12 or newer).
args:
    mcpServerVersion:
        default: 3.4.1
        description: exa-mcp-server (npm) version to package
        pattern: ^[0-9]+\.[0-9]+\.[0-9]+$
        buildArg: EXA_MCP_SERVER_VERSION