Let’s be honest: you’ve probably spent more time wrestling API keys, writing brittle requests.post() wrappers, and debugging why your LLM agent still can’t book a Zoom meeting or fetch your Notion tasks than actually building the thing you care about. I’ve been there — running a self-hosted LangChain agent on a $5 DigitalOcean droplet, watching it fail silently because NOTION_INTEGRATION_TOKEN wasn’t injected just right into the right tool call, or because the OpenWeather API endpoint changed again. That’s why I dropped everything two weeks ago when I found jentic-mini — a lean, Python-based, self-hosted API execution layer that actually works as advertised. It’s not another orchestration framework or a full agent runtime. It’s the boring-but-critical plumbing: your agent says “get my calendar events for tomorrow”, and jentic-mini figures out which API to hit, grabs the right token from your vault, marshals the payload, handles 429s, and returns clean JSON. And it has 97 GitHub stars (as of May 2024), zero marketing fluff, and — here’s the kicker — it runs comfortably on a Raspberry Pi 4 with 4GB RAM.

What Is Jentic Mini? (And Why It’s Not Another “Agent Orchestrator”)

Jentic Mini is not an LLM orchestrator. It doesn’t do memory, planning, or tool selection. It doesn’t host models or manage prompts. It’s one thing, and one thing only: a runtime API broker for LLM agents.

Think of it as the curl that knows your secrets, understands your agent’s intent, and speaks API contracts. When your agent outputs a tool call like:

{
  "tool": "notion.search_pages",
  "args": { "query": "Q2 2024 OKRs" }
}

Jentic Mini matches that notion.search_pages string to a pre-registered API spec (in OpenAPI 3.0 format), injects your NOTION_INTEGRATION_TOKEN from environment or a secrets backend, validates the args against the spec, signs the request (if needed), retries on rate limits, and returns the parsed response — all before your agent sees it.

It’s built in Python 3.11+, uses FastAPI for the HTTP layer, and leans hard on pydantic for validation. The core is ~800 lines of clean, readable code. No abstraction layers hiding bugs. No “enterprise” configuration DSL. Just YAML specs, env vars, and HTTP.

How Jentic Mini Compares to Alternatives

If you’ve tried stitching together agents with tools, you’ve likely touched one (or all) of these:

  • LangChain’s RequestsToolkit: Requires manual credential injection per tool, no shared auth context, no retry/backoff, and zero OpenAPI validation. I once spent 3 hours debugging why my requests.get() was sending Authorization: Bearer null — because the env var wasn’t loaded in the right Python process. Jentic Mini eliminates that class of footgun.

  • Toolformer or OpenAgents’ tool servers: These are heavier — often bundled with model serving, UIs, and custom agent runtimes. Jentic Mini has no frontend, no database, and no model dependencies. It’s a single HTTP endpoint (POST /execute). That means lower attack surface, faster updates, and way less RAM pressure. On my test NUC (Intel i3, 8GB RAM), jentic-mini sits at ~45MB RAM idle, and peaks at ~90MB under sustained tool-call load (10 req/sec). LangChain + Llama.cpp + custom tool server? That same NUC was swapping.

  • n8n or Zapier self-hosted: Overkill. They’re workflow engines — great for human-triggered automations, terrible for high-frequency, low-latency, JSON-in/JSON-out agent tool calls. Jentic Mini responds in ~120–350ms median (tested with local Notion + GitHub APIs), vs n8n’s typical 800ms+ overhead.

  • Custom flask + requests wrapper: Yeah, I’ve written three of those. They all rot. Jentic Mini gives you OpenAPI spec enforcement, credential templating (e.g., {{ secrets.NOTION_TOKEN }}), and HTTP client best practices (keep-alive, timeout tuning, retry jitter) out of the box.

The TL;DR: if your agent needs to talk to real APIs, and you’re tired of writing if tool == "github.create_issue": ... blocks, jentic-mini is the missing middle layer.

Installation & Running with Docker Compose

The easiest, most production-ready way is Docker. The project provides an official image (jentic/jentic-mini:0.2.1, as of May 2024) and a clean docker-compose.yml.

Here’s what I run on my homelab (Ubuntu 22.04, Docker 24.0.7):

# docker-compose.yml
version: '3.8'
services:
  jentic-mini:
    image: jentic/jentic-mini:0.2.1
    ports:
      - "8000:8000"
    environment:
      - JENTIC_API_SPECS_DIR=/app/specs
      - JENTIC_SECRETS_BACKEND=env
      # Optional: for basic auth (recommended in prod)
      - JENTIC_BASIC_AUTH_USERNAME=agent
      - JENTIC_BASIC_AUTH_PASSWORD=super-secure-change-me
    volumes:
      - ./specs:/app/specs:ro
      - ./secrets.env:/app/secrets.env:ro
    restart: unless-stopped

Then create your API specs. Drop them in ./specs/ as YAML files. Here’s a real notion.yaml I use (simplified):

# ./specs/notion.yaml
openapi: 3.0.3
info:
  title: Notion API
  version: "2022-06-28"
servers:
  - url: https://api.notion.com/v1
paths:
  /search:
    post:
      summary: Search pages and databases
      operationId: search_pages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: Text to search for
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object

Now, for secrets: ./secrets.env (yes, it’s literal .env format):

NOTION_INTEGRATION_TOKEN=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Start it:

docker compose up -d

Test it:

curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'agent:super-secure-change-me' | base64)" \
  -d '{
    "tool": "notion.search_pages",
    "args": {"query": "OKR"}
  }'

You’ll get clean JSON back — no raw HTTP headers, no auth leakage, no manual JSON parsing.

Configuring API Specs and Runtime Secrets

Jentic Mini supports two secrets backends out of the box:

  • env: reads from environment (what we used above)
  • file: reads from a .env file at runtime (useful if you don’t want secrets in Docker env vars)

To use file-based secrets, change your compose:

environment:
  - JENTIC_SECRETS_BACKEND=file
  - JENTIC_SECRETS_FILE_PATH=/app/secrets.env

And make sure that file is mounted.

Specs are the soul of jentic-mini. A few real-world tips I learned the hard way:

  • Don’t skip operationId: This is how your agent references the tool. It must match exactly what your agent outputs. I once had notion.search vs notion.search_pages — jentic-mini 404’d silently until I checked the logs.

  • Use x-jentic-credential to pin auth: Not all APIs use Bearer. For GitHub, I added this to the paths./repos/{owner}/{repo}/issues.post section:

x-jentic-credential:
  type: bearer
  token: "{{ secrets.GITHUB_TOKEN }}"
  • Validation is strict but helpful: If your agent sends {"query": 123} (int instead of string), jentic-mini returns a 400 with "args.query must be string". This caught a real bug where my agent was coercing dates to numbers.

Who Is This For? (Spoiler: It’s Not for Everyone)

Jentic Mini is not for:

  • Beginners learning LLMs. You need to understand tool calling, OpenAPI, and basic API auth to use this well.
  • Teams wanting a no-code UI. There is no dashboard, no logs UI, no audit trail (yet).
  • Use cases requiring OAuth2 dance or PKCE flows. It supports static tokens and simple Bearer/Basic auth only.

It is for:

  • Self-hosters who run agents on Homelab/NAS/cheap VPS and hate leaking secrets in Python files.
  • AI hackers building custom agents (e.g., with llama-cpp-python + custom tool loop) and tired of reinventing auth.
  • Teams standardizing on OpenAPI for internal tools — you can drop your internal REST API spec in ./specs/ and instantly expose it to any agent.
  • Privacy-first folks: All credential injection happens in-process, never hits disk (unless you use file backend), and no telemetry is collected.

Hardware-wise? I’ve run it on:

  • Raspberry Pi 4 (4GB): ✅ Stable, ~300ms p95 latency
  • Intel NUC (i3-10110U, 8GB): ✅ 120ms p95, handles 25+ req/sec
  • Old Mac Mini (2012, 16GB RAM): ✅ Overkill, but fine

Minimum viable: 2GB RAM, 1 vCPU, Python 3.11+. It’s not CPU-bound — it’s I/O bound, so fast network matters more than raw cores.

The Honest Verdict: Should You Deploy It Now?

Yes — if you’re already neck-deep in agent tooling and hitting auth/validation pain points. I’ve run jentic-mini:0.2.1 for 14 days straight across two agents (one Notion + GitHub, one internal weather + calendar stack). Zero crashes. Zero memory leaks. Logs are clean and actionable (INFO: Executing notion.search_pages with args={'query': 'OKR'}).

But — and this is critical — it’s early. Rough edges I hit:

  • No built-in rate limiting per API key: You must configure FastAPI middleware or reverse-proxy (nginx) to throttle. I added this to nginx:

    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
location /execute {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://jentic-mini:8000;
}

  • No secrets rotation UI: You restart the container to pick up new tokens. Fine for me, but a blocker for some teams.

  • OpenAPI import is manual: No openapi-generator-style CLI to auto-scaffold specs from live endpoints. You write them by hand (or use Swagger Editor + export).

  • No Prometheus metrics yet: I patched in a quick /metrics endpoint using starlette-prometheus, but it’s not upstream.

That said — the maintainer is responsive (merged my docs PR in 6 hours), the code is delightfully readable, and the scope is intentionally narrow. This isn’t trying to be LangChain 2.0. It’s trying to be the libc of agent API calls. And for that? It’s already better than what I’d cobbled together.

So — deploy it. Start small: one spec, one agent, one token. Watch your agent stop failing on auth and start doing. And when your Notion search actually returns pages instead of a 401, you’ll get why 97 people starred it in under two months.

It’s not magic. It’s just done right. And in self-hosting, that’s rarer — and more valuable — than you think.