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

> Learn essential Colibri development security considerations including API hardening, authentication, host validation, CORS, and rate limiting to protect against attacks.

- Repository: [Vincenzo Fornaro/colibri](https://github.com/JustVugg/colibri)
- Tags: best-practices
- Published: 2026-09-12

---

**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`](https://github.com/JustVugg/colibri/blob/main/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`](https://github.com/JustVugg/colibri/blob/main/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.

```bash

# 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.

```bash
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.

```bash
./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.

```bash
./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.

```nginx
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`](https://github.com/JustVugg/colibri/blob/main/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.

```json
{
  "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`](https://github.com/JustVugg/colibri/blob/main/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`](https://github.com/JustVugg/colibri/blob/main/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.