Getting Started with OpenSquilla: Install with Docker in 10 Minutes

Getting OpenSquilla Running — Your First 10 Minutes

I'll walk through the Docker setup since that's the fastest way to try it. No Python version conflicts, no dependency hell — just Docker and two commands.

Prerequisites

Step 1: Pull and Run

docker pull ghcr.io/opensquilla/opensquilla:latest
docker run -d --name opensquilla \
  -p 18791:18791 \
  -e OPENROUTER_API_KEY=your_key_here \
  ghcr.io/opensquilla/opensquilla:latest

The gateway listens on port 18791 by default — that's intentionally not 8080 to avoid conflicts with other services you might have running. Took me a minute to figure out why mine wasn't working at first (I assumed port 8080).

💡 What you should see: After 5-10 seconds, the health check at http://localhost:18791/healthz should return HTTP 200 with {"status":"ok"}. If you get connection refused, give it a few more seconds on the cold start.

Step 2: Docker Compose (Recommended)

For a production setup with persistent state, create a docker-compose.yml:

services:
  opensquilla:
    image: ghcr.io/opensquilla/opensquilla:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:18791:18791"
    volumes:
      - opensquilla-state:/var/lib/opensquilla
    environment:
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
    healthcheck:
      test: ["CMD-SHELL", "curl --fail http://127.0.0.1:18791/healthz || exit 1"]
      interval: 30s
      timeout: 5s
      start_period: 10s
      retries: 3

volumes:
  opensquilla-state:

⚠️ Common mistake: I set OPENSQUILLA_LISTEN=127.0.0.1 thinking it was more secure. Wrong — inside the container it needs 0.0.0.0 so Docker port publishing works. The real security layer is the host-side -p 127.0.0.1:18791:18791 binding. Don't change the in-container address.

Step 3: Configure Providers

OpenSquilla supports 20+ providers out of the box. The simplest setup is an OpenRouter key — it gives you access to dozens of models through one API. Set it as an environment variable and the agent auto-detects available models.

If you want the SquillaRouter (the on-device model router), add OPENSQUILLA_INSTALL_PROFILE=recommended. It downloads ONNX Runtime and LightGBM models for smart routing — about 500MB on first startup.

Real Talk: Cold Start & RAM

Cold start (first request after a fresh container) takes about 8-12 seconds on a 4 vCPU machine. After that, warm requests are sub-second for most models. RAM usage sits around 1.2GB idle, spiking to 3GB under load with SquillaRouter active. Without the router, expect ~600MB idle.

Final Thoughts

OpenSquilla's Docker setup is refreshingly clean. The compose.yml in the repo is the best starting point — just copy it, add your API keys in a .env file, and docker compose up -d. Ten minutes from zero to a running multi-provider AI agent.