JuliusBrussee/caveman · error

caveman-proxy not found; run `caveman setup --install`

Error message

caveman-proxy not found; run `caveman setup --install`

What it means

nativeProxyBinaryRequired applies only when wrapMode(gw) is "local": local wrapping needs the caveman-proxy Go binary. resolveGoBin("caveman-proxy", "CAVEMAN_PROXY_BIN") returning nothing means the proxy cannot be spawned, so the native runtime setup aborts with the remediation command. (A separate message covers the version-capability mismatch.)

Source

Thrown at packages/cli/src/index.ts:6013

function parseJsonFileObject(path: string, bytes: Buffer | null): Record<string, unknown> {
  if (!bytes || bytes.length === 0) return {};
  const parsed = JSON.parse(bytes.toString("utf8"));
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${path} is not a JSON object`);
  return parsed as Record<string, unknown>;
}

function nativeMcpBinaryRequired(): string {
  const compatible = probeMcpBinary();
  if (!compatible) throw new Error("caveman-mcp not found; run `caveman setup --install`");
  if (!compatible.probe.current) throw new Error(`caveman-mcp ${compatible.probe.version} lacks current mcp_recovery capability; run \`caveman setup --install\``);
  return compatible.binary;
}

function nativeProxyBinaryRequired(gw: string): void {
  if (wrapMode(gw) !== "local") return;
  const binary = resolveGoBin("caveman-proxy", "CAVEMAN_PROXY_BIN");
  if (!binary) throw new Error("caveman-proxy not found; run `caveman setup --install`");
  const probe = probeVersionedBinary(binary, "native_runtime_v1");
  if (!probe.current) throw new Error(`caveman-proxy ${probe.version} lacks current native_runtime_v1 capability; run \`caveman setup --install\``);
}

function nativeHostProbe(agent: AgentProfile): { binary: string | null; launchable: boolean; version: string | null; error: string | null } {
  const binary = which(binOf(agent));
  if (!binary) return { binary: null, launchable: false, version: null, error: "binary_not_found" };
  try {
    const invocation = portableInvocation(binary, ["--version"]);
    const out = spawnSync(invocation.command, invocation.args, { encoding: "utf8", timeout: 3000 });
    if (out.error) return { binary, launchable: false, version: null, error: boundedHookString(out.error.message, 240) ?? "version_probe_failed" };
    const value = `${out.stdout ?? ""} ${out.stderr ?? ""}`.trim();
    if (out.status !== 0) return { binary, launchable: false, version: value ? value.slice(0, 160) : null, error: `version_probe_exit_${out.status ?? "unknown"}` };
    return { binary, launchable: true, version: value ? value.slice(0, 160) : null, error: null };
  } catch {
    return { binary, launchable: false, version: null, error: "version_probe_failed" };
  }
}

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Run `caveman setup --install` to install caveman-proxy
2. Add the Go bin directory to PATH (e.g. export PATH="$PATH:$(go env GOPATH)/bin")
3. Set CAVEMAN_PROXY_BIN to an absolute existing caveman-proxy binary if installed at a custom location
4. Or switch the gateway to a non-local wrap mode which does not require the proxy

Example fix

# before
caveman setup --agent-native codex  # Error: caveman-proxy not found (local wrap mode)

# after
export PATH="$PATH:$HOME/go/bin"
caveman setup --install
caveman setup --agent-native codex

import { which } from "caveman";
if (wrapMode(gateway) === "local" && !process.env.CAVEMAN_PROXY_BIN && !which("caveman-proxy")) {
  throw new Error("local wrap mode requires caveman-proxy; run `caveman setup --install` or pick a non-local gateway");
}

try {
  nativeProxyBinaryRequired(gateway);
} catch (error) {
  if (/caveman-proxy not found/.test((error as Error).message)) {
    // either provision the binary or fall back to a gateway mode that does not need it
    await ensureGoBinariesInstalled();
    nativeProxyBinaryRequired(gateway);
  } else throw error;
}

When it happens

Trigger: Choosing a local wrap mode gateway in setup while caveman-proxy is not installed: fresh environment, Go bin dir missing from PATH, CAVEMAN_PROXY_BIN pointing at a deleted path, non-local modes skip this entirely.

Common situations: First-time local-mode setup without running --install; PATH reset in CI or after shell migration; binary pruned by disk cleanup.

Related errors

• caveman-mcp not found; run `caveman setup --install`
• registry output has no capabilities
• cave_transform_registry_unavailable: run caveman setup or se
• ${agent} native integration postflight is ${status.state}
• agent-native setup failed: ${(error as Error).message}${roll

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/35665f7a38c7414f. Report an issue: GitHub.