Installing the Gateway

The Ithil Gateway is the process that speaks MCP to agents and proxies approved calls to your downstream API. It requires Redis and an ONNX embedding model at startup.

Docker (recommended)

docker run


docker run -d \
  --name ithil-gateway \
  -p 5100:8080 \
  -e Ithil__LicenseKey="your-license-key" \
  -e Ithil__Jwt__SigningKey="your-32-byte-or-longer-signing-key" \
  -e Ithil__ToolRegistry__DownstreamBaseUrl="http://your-api:5200" \
  -e ConnectionStrings__Redis="your-redis:6379" \
  ithilsoftware/gateway:latest

Never commit Ithil__Jwt__SigningKey or Ithil__Admin__ApiKey to source control. Use Docker secrets, Azure Key Vault, or a secrets manager for production deployments.

Manual (dotnet run)

Clone the repository and run the gateway project directly:


git clone https://github.com/robcross1977/Ithil.git
cd Ithil
dotnet run --project src/Ithil.Gateway

Or install as a global tool (when published):


dotnet tool install -g Ithil.Gateway
ithil-gateway

For production, also set Ithil__Admin__ApiKey to enable the admin token endpoint — see Agent Management.

Get a license key (free for non-commercial use) at ithil.software/register — see Licensing for details.

Minimum appsettings.json:


{
  "Ithil": {
    "LicenseKey": "your-license-key",
    "Jwt": {
      "SigningKey": "your-32-byte-or-longer-signing-key",
      "Issuer": "ithil-dev",
      "Audience": "ithil-gateway"
    },
    "ToolRegistry": {
      "DownstreamBaseUrl": "http://localhost:5200"
    },
    "SemanticCache": {
      "ModelPath": "models/all-MiniLM-L6-v2.onnx",
      "VocabPath": "models/vocab.txt"
    }
  },
  "ConnectionStrings": {
    "Redis": "localhost:6379"
  }
}

Health checks

Endpoint	Purpose
`GET /health/live`	Always `200 OK` if the process is running. Use for container liveness probes.
`GET /health/ready`	`200 OK` when Redis and the ONNX embedding model are loaded and ready. Use for load balancer readiness gates. Never route traffic until this is healthy.

Example ready response:


{
  "status": "Healthy",
  "components": {
    "redis": { "status": "Healthy" },
    "onnxModel": { "status": "Healthy" }
  }
}

Ports and network

Item	Default	Override
Gateway HTTP port	`8080` (container), `5100` (manual)	`--urls` flag or `ASPNETCORE_URLS` env var
Redis	`localhost:6379`	`ConnectionStrings__Redis` env var
Downstream API	(required)	`Ithil__ToolRegistry__DownstreamBaseUrl`

The gateway must be able to reach:

Redis (for budget and cache)
Your downstream ASP.NET API (to forward tool calls and poll /ithil/schema)

Startup gates

The gateway performs startup validation and refuses to start if:

Condition	Error message
`LicenseKey` is missing or empty	`No Ithil license key found. Register for free at ithil.software/register.`
`LicenseKey` signature is invalid or tampered	`The Ithil license key is invalid or has been tampered with.`
Redis is unreachable	`Failed to connect to Redis at {address}. Ensure Redis is running and the connection string is correct.`
ONNX model file missing	`Semantic cache model not found at path '{path}'. Set Ithil:SemanticCache:ModelPath to a valid .onnx file.`
`SigningKey` is missing or too short	`Ithil:Jwt:SigningKey must be at least 32 bytes for HMAC-SHA256.`
`DownstreamBaseUrl` is missing	`Ithil:ToolRegistry:DownstreamBaseUrl is required.`

Fix the reported condition and restart. The ONNX model can be downloaded from the releases page or bundled in the Docker image.