How to Set Up and Configure wigolo's REST API Server with Token Authentication

Set the WIGOLO_API_TOKEN environment variable when running wigolo serve on any non-loopback interface to require Authorization: Bearer <token> headers on all /v1/*, /openapi.json, /mcp, and /sse endpoints while keeping the /health endpoint publicly accessible for load balancer probes.

The KnockOutEZ/wigolo repository exposes a plain-JSON REST surface via the wigolo serve command. While the daemon binds to 127.0.0.1:3333 without authentication by default, any non-loopback configuration triggers a fail-closed security policy that mandates bearer token authentication according to docs/rest-api.md and docs/configuration.md.

Understanding the Fail-Closed Security Model

When binding to 0.0.0.0 or any public IP address, wigolo aborts startup unless it detects a valid authentication token. This prevents accidental exposure of intelligence endpoints to untrusted networks. Internally, the token is read once at startup and stored in a process-private variable; subsequent requests validate the Authorization header using a case-insensitive comparison against the stored bearer scheme.

Configuring Token Sources

Environment Variable Method

Set WIGOLO_API_TOKEN before launching the daemon. This approach is suitable for development environments or secret managers that inject variables directly into the process environment.

export WIGOLO_API_TOKEN=$(openssl rand -hex 32)
wigolo serve --host 0.0.0.0 --port 3333

File-Based Secret for Containerized Deployments

For Docker or Kubernetes deployments, mount the token as a file and reference it via WIGOLO_API_TOKEN_FILE. This pattern prevents the token from appearing in process listings, following the security hardening guidance in docs/privacy-security.md.

# Create secret file on the host

echo "$WIGOLO_API_TOKEN" > /run/secrets/wigolo-token

docker run -p 3333:3333 \
  -e WIGOLO_API_TOKEN_FILE=/run/secrets/wigolo-token \
  -v /run/secrets/wigolo-token:/run/secrets/wigolo-token:ro \
  ghcr.io/knockoutez/wigolo serve --host 0.0.0.0

Starting the Server on Public Interfaces

When the daemon detects a non-loopback bind and cannot locate a token via WIGOLO_API_TOKEN or WIGOLO_API_TOKEN_FILE, it aborts with a clear error message before opening network sockets. Protected endpoints include:

• /v1/tools
• /v1/search
• /openapi.json
• /mcp
• /sse

The /health endpoint remains accessible without authentication for monitoring and load balancer health probes.

Making Authenticated Requests

All protected endpoints require the Authorization header with the bearer token configured at startup. Concrete examples are also available in examples/rest-curl/README.md.

Listing Available Tools

curl -s -H "Authorization: Bearer $WIGOLO_API_TOKEN" \
     http://<host>:3333/v1/tools

Performing Searches

curl -s -X POST http://<host>:3333/v1/search \
     -H "Authorization: Bearer $WIGOLO_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"query":"local-first web intelligence","max_results":5}'

Health Checks

Load balancers can probe the service without providing a token:

curl -s http://<host>:3333/health

Disabling Authentication (Development Only)

Override the fail-closed policy using the --allow-unauthenticated flag or by setting WIGOLO_SERVE_ALLOW_UNAUTHENTICATED=1. This bypass is explicitly documented in docs/self-hosting.md for local development only and should never be used in production deployments.

SDK Configuration

Both official SDKs mirror the REST API authentication model:

• TypeScript SDK: Reads the WIGOLO_API_TOKEN environment variable by default, as documented in sdks/typescript/README.md
• Python SDK: Accepts a token parameter that maps to the bearer header, detailed in sdks/python/README.md

Summary

• Fail-Closed Default: Non-loopback binds (0.0.0.0 or public IPs) require WIGOLO_API_TOKEN or WIGOLO_API_TOKEN_FILE
• Header Format: Protected endpoints require Authorization: Bearer <token> with case-insensitive scheme matching
• Health Endpoint: The /health route remains publicly accessible for infrastructure monitoring
• Container Security: Prefer WIGOLO_API_TOKEN_FILE mounted as a Docker secret over environment variables
• Development Override: Use --allow-unauthenticated or WIGOLO_SERVE_ALLOW_UNAUTHENTICATED=1 strictly for local testing

Frequently Asked Questions

What happens if I start wigolo on 0.0.0.0 without setting a token?

The server aborts during initialization with a clear error message stating that authentication is required for non-loopback interfaces. This prevents accidental exposure of sensitive endpoints before the process opens network sockets.

Which endpoints require the bearer token?

All routes under /v1/*, plus /openapi.json, /mcp, and /sse, require the Authorization: Bearer <token> header. The only exception is /health, which remains open for load balancer probes and monitoring systems.

How do I rotate the authentication token?

Restart the wigolo process with the new token value. Since the token is loaded once at startup into a process-private variable, token rotation requires a process restart. For zero-downtime deployments, drain connections via a load balancer before switching instances.

Can I use Docker secrets instead of environment variables?

Yes. Write the token to a file (e.g., /run/secrets/wigolo-token), mount it into the container, and set WIGOLO_API_TOKEN_FILE to that path. This method keeps credentials out of the process environment and is recommended in docs/privacy-security.md for production containerized deployments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}