Run the tools worker (auxot-tools)

Why this matters

GPU and CLI workers answer generate the next tokens. Tools workers answer run the thing the model just asked for (web fetch, search, sandboxed code, and MCP subprocesses) and return structured results so the conversation can continue (Tools Workers).

Without a connected tools worker, tool calls stall or never complete: the router (OSS) or Auxot Server (commercial) needs a live process speaking the tools protocol.

Two wiring stories share one binary:

Nothing executes until you start auxot-tools, you inject secrets, and you confirm connectivity — same discipline as GPU workers, different blast radius.

Quick start

A: OSS router path

1. Router side — set AUXOT_TOOLS_KEY_HASH to the Argon2id hash of the tools key you’ll use (OSS Configuration).
2. Worker side — download auxot-tools or docker pull ghcr.io/auxothq/auxot-tools:latest (Tools Workers).
3. Run — AUXOT_TOOLS_KEY=tls_xxx AUXOT_ROUTER_URL=host:port ./auxot-tools (example from Tools Workers).
4. Credentials — for Brave-backed built-ins, use the AUXOT_TOOLS_{TOOL}__{VAR} pattern (double underscore between tool name and credential name) (Tools Workers, OSS Configuration).
5. Optional guardrail — AUXOT_ALLOWED_TOOLS=code_executor,web_fetch on the router (Tools Workers).

B: Auxot Server path

1. Create a tool policy in Settings → Tool Policies and copy the tool connector key shown once (tools.{id}.{secret}) (Define a tool policy).
2. Run auxot-tools from the same GitHub Releases / ghcr.io/auxothq/auxot-tools image as OSS (Tools Workers).
3. Point at your Auxot HTTPS origin — same AUXOT_ROUTER_URL style URL you use for other outbound workers (compare Agents agent-worker examples); authenticate with the connector key string (Tool Worker Policies).
4. Built-ins — commercial docs expect BRAVE_API_KEY (or equivalent) in the tools worker environment when web_search / web_answers are on (Tool Worker Policies). Resolve OAuth-backed MCP per policy sources there; credentials decrypt inside the worker process.
5. Verify — open Chat with an agent that has the policy attached; prompt for something only a tool answers (Define a tool policy smoke-test wording).

Done? One successful tool round-trip proves the chain: policy → worker → subprocess/schema → model.

The agent can do that?

1. Sidecar layout vs cramming everything on one VM

Chat → Admin Agent:

We're placing auxot-tools next to Auxot Server for [team size / compliance region]. Compare sidecar container vs shared host for egress control, secret rotation, and blast radius if MCP packages phone home — bullets only.

Why it’s non-obvious: MCP stdio servers open whatever egress their npm packages open (Tool Worker Policies); network policy belongs in your infra diagram; Admin Agent summarizes tradeoffs after you paste constraints.

2. Brave + built-in credential sanity

Tool policy "[name]" has web_search enabled for tools worker deploy on [k8s | systemd | docker compose]. List env vars I must set on the worker host and which ones come from OAuth vs static secrets per manual.

Why it’s non-obvious: OSS naming (AUXOT_TOOLS_WEB_SEARCH__…) and commercial rows (BRAVE_API_KEY on the worker) both appear in docs; paste edition + policy name so the reply stays anchored.

3. OSS allowlist before widening MCP

OSS router currently allows all registered tools. Draft a conservative first `AUXOT_ALLOWED_TOOLS` comma list for internal dev-only traffic — assume code_executor + web_fetch first, search later — and what breaks if I omit a tool my prompts already rely on.

Why it’s non-obvious: Empty allowlist means all on OSS (Tools Workers); tightening without an inventory leaves completions stuck in the middle of a tool loop.

Go deeper

MCP runtime differs by image

OSS Docker notes emphasize bun + pnpm for on-demand MCP (Tools Workers). Commercial Tool Worker Policies describe npx -y <package>@<version> for stdio MCP (Tool Worker Policies). Same binary family; the image and docs you are running are what matter when debugging spawn failures.

Shell tools (OSS)

Besides MCP, OSS workers can load ./tools/*.sh + .tool.json descriptors from a local directory (Tools Workers). Commercial governance flows through policies instead; don’t assume shell-tool folders apply to hosted Auxot unless your deployment docs say so.

Direct Tools API (OSS router)

GET /api/tools/v1/list and POST /api/tools/v1/execute accept the rtr_ caller key (Tools Workers, OSS API): useful health checks without running a full chat loop.

Built-in matrix

Sandbox capabilities for code_executor and related rows are documented per edition (Tools Workers, Tool Worker Policies); verify your row before promising Python vs JS-only behavior in runbooks.

Walkthrough

Step 1: Pick path A or B

Running an OSS experiment? Follow §A for keys. Running a production Auxot org? Follow §B for the connector key.

Step 2: Install

Binary curl from GitHub Releases or Docker image ghcr.io/auxothq/auxot-tools:latest (Tools Workers).

Step 3: Export secrets

• OSS Brave pattern: AUXOT_TOOLS_WEB_SEARCH__BRAVE_SEARCH_API_KEY, AUXOT_TOOLS_WEB_ANSWERS__… (Tools Workers).
• Server: satisfy BRAVE_API_KEY (and MCP env/OAuth) per policy rows (Tool Worker Policies).

Step 4: Launch process

OSS:

export AUXOT_TOOLS_KEY=tls_xxxxxxxx
export AUXOT_ROUTER_URL=127.0.0.1:8080
./auxot-tools

Server: set AUXOT_ROUTER_URL to your Auxot HTTPS origin (same idea as agent workers in Agents). Set the worker secret env var your self-hosting or compose template documents; many installs use AUXOT_TOOLS_KEY with the full tools.{id}.{secret} connector string copied from Settings → Tool Policies (Tool Worker Policies).

export AUXOT_ROUTER_URL=https://ai.yourcompany.com
# export <YOUR_TEMPLATE’S_SECRET_VAR>=tools.xxxxx.yyyyy
./auxot-tools

Confirm logs show registration; no registration → completions with tools hang.

Step 5: Verify

• Server: Chat prompt requiring web_fetch / MCP (Define a tool policy style).
• OSS: curl tools list/execute with rtr_ bearer (Tools Workers) or a completion payload that invokes a built-in you enabled.

Step 6: Document rotation

Connector keys regenerate from Settings → Tool Policies (invalidates old) (Tool Worker Policies). OSS tls_ keys require coordinated router hash updates; treat them like GPU admin keys (Run the open-source inference router mindset).

What’s next

• → Run the open-source inference router. When auxot-tools should attach to auxot-router, not Server.
• → Define a tool policy. Decide which tools each agent can call before you scale worker replicas.
• → Add an MCP server. Catalog, Validate, and credential sources on Server.
• → Build a cross-meeting commitments ledger. Tool-heavy automation still owes humans a durable paper trail; keep the ledger beside the job records in Audit Logs.
• → Tools Workers. Installation, env patterns, Direct Tools API.
• → Tool Worker Policies. Connector keys, OAuth MCP, team assignment.

Reference

• Images / binaries: ghcr.io/auxothq/auxot-tools, releases under github.com/auxothq/auxot
• OSS: Tools Workers, OSS Configuration, OSS Deployment (image size row)
• Commercial: Tool Worker Policies, Agents (outbound worker URL pattern)
• See also: Stay ahead of agent usage and cost, Build a cross-meeting commitments ledger, Connect a GPU worker (different worker SKU, same “ops owns the process” lesson), Call the OpenAI-compatible Chat Completions API (tool_calls clients), Call the Anthropic-compatible Messages API (HTTP shape when testing OSS router stacks)