Security Considerations for Colibri Development: Hardening the HTTP API and Desktop UI

Colibri exposes an HTTP API and desktop UI that require authentication tokens, host validation, CORS restrictions, and rate limiting to prevent unauthorized access, DNS rebinding, and denial-of-service attacks.

When deploying the JustVugg/colibri inference engine, understanding the security considerations for Colibri development is essential to safeguard model endpoints against common web vulnerabilities. This low-level C engine wrapped by a Python/CLI layer provides both a server mode (coli serve) and a Tauri-based desktop application, each requiring specific hardening configurations to prevent unauthorized inference access and resource exhaustion.

Authentication and API Key Management

The Colibri server implements bearer token authentication controlled entirely through environment variables. According to docs/api.md, the service only enables authentication when the COLI_API_KEY environment variable is set to a non-empty value. If this variable is unset, the server runs without authentication, which is only acceptable for localhost-bound development endpoints.

The OpenAPI specification in docs/api-reference/openapi.json declares two security mechanisms: bearerAuth for standard Bearer token headers and apiKeyAuth for x-api-key header authentication. Clients generated from this specification automatically include these headers when configured with valid credentials.

# Export a strong secret (store it safely, e.g., in a .env file)

export COLI_API_KEY=super-secret-token

# Run the service with authentication enabled

./coli serve --model /path/to/model --host 127.0.0.1 --port 8000

Network Security Controls

Host Validation and DNS Rebinding Protection

Colibri implements strict host validation to prevent DNS rebinding attacks. The --allowed-host flag (or COLI_ALLOWED_HOSTS environment variable) builds an allow-list of hostnames and IP addresses that the server will respond to. This prevents attackers from pointing public DNS records at your server and bypassing authentication checks through hostname confusion.

export COLI_ALLOWED_HOSTS=api.my-colibri.com,192.168.1.100

./coli serve \
  --model /nvme/glm52_i4 \
  --host 0.0.0.0 \
  --port 8000 \
  --allowed-host api.my-colibri.com

CORS Origin Restrictions

By default, Colibri permits only the Vite development server and local Tauri origins. Production deployments must explicitly whitelist additional front-end origins using the --cors-origin flag. The wildcard ('*') option is only safe on trusted LANs; public deployments should specify exact origins to prevent cross-origin attacks from malicious web pages.

./coli serve \
  --model /nvme/glm52_i4 \
  --cors-origin https://app.example.com

Rate Limiting and Denial-of-Service Protection

The engine caps concurrent generation requests using --max-queue and --queue-timeout parameters. When the request queue exceeds the configured limit, Colibri returns an HTTP 429 Too Many Requests error in OpenAI-compatible format, preventing resource exhaustion from uncontrolled parallel requests.

./coli serve \
  --model /nvme/glm52_i4 \
  --max-queue 4 \
  --queue-timeout 120

Transport Layer Security

Colibri's HTTP server does not provide TLS encryption. Production deployments must front the service with a reverse proxy such as Nginx or Caddy to handle TLS termination. Bind the Colibri server to 127.0.0.1 to ensure it only accepts proxied connections from the local machine.

server {
    listen 443 ssl;
    server_name api.my-colibri.com;

    ssl_certificate     /etc/ssl/certs/fullchain.pem;
    ssl_certificate_key /etc/ssl/private/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Desktop UI Sandboxing

The Tauri-based desktop application runs under a restrictive Content Security Policy (CSP) defined in desktop/src-tauri/tauri.conf.json. The configuration disables remote content loading and limits the web view's capabilities to local assets only, minimizing the attack surface from malicious remote resources.

{
  "security": {
    "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';"
  },
  "allowlist": {
    "all": false,
    "http": {
      "all": false
    }
  }
}

Secret Management and Environment Variables

Colibri reads all sensitive configuration from environment variables at runtime; no secrets are hard-coded in the source. The repository provides an .env.example file showing expected variables without exposing real values. Never commit .env files containing production secrets to version control.

Tool-Calling Validation

When models emit tool calls, the server validates the structure against the active engine's native format according to docs/api.md. Invalid tool blocks are rejected with explicit error messages rather than being silently ignored, preventing malformed requests from triggering unintended behavior.

Summary

• Enable authentication by setting COLI_API_KEY before starting the server to prevent unauthorized API access.
• Validate hostnames using --allowed-host or COLI_ALLOWED_HOSTS to block DNS rebinding attacks.
• Restrict CORS origins to specific trusted domains rather than using wildcards in production.
• Implement rate limiting with --max-queue and --queue-timeout to prevent denial-of-service via request flooding.
• Terminate TLS at a reverse proxy (Nginx/Caddy) since Colibri does not natively support HTTPS.
• Secure the desktop UI by auditing desktop/src-tauri/tauri.conf.json to ensure CSP restrictions and disabled remote content loading.
• Protect secrets by using .env files locally and ensuring they are listed in .gitignore.

Frequently Asked Questions

How do I enable authentication on the Colibri API server?

Export the COLI_API_KEY environment variable with a strong, random token before starting the server. The coli serve command automatically enables bearer token authentication when this variable is present, requiring all API requests to include an Authorization: Bearer <token> or x-api-key: <token> header.

What is the purpose of the --allowed-host flag in Colibri?

The --allowed-host flag prevents DNS rebinding attacks by maintaining a strict allow-list of hostnames and IP addresses that the server will accept requests from. Without this protection, an attacker could point a public DNS name at your server and potentially bypass security checks meant for localhost-only access.

Does Colibri support HTTPS/TLS encryption natively?

No, Colibri does not implement TLS in its HTTP server. For secure production deployments, you must place a reverse proxy such as Nginx or Caddy in front of Colibri to handle TLS termination, keeping the Colibri service bound to 127.0.0.1 so it only accepts connections from the local proxy.

How does Colibri protect against denial-of-service attacks?

Colibri implements request queue limits via the --max-queue parameter, which caps the number of concurrent generation requests. When the queue is saturated, the server returns HTTP 429 (Too Many Requests) errors, preventing resource exhaustion from excessive parallel connections.

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