AIHelms: a self-hosted gateway and cost ledger for enterprise LLM access

The problem AIHelms targets: model keys without a ledger

Most companies adopt LLMs the same way they adopted SaaS a decade ago. One team gets an OpenAI key, another signs an Azure contract, a third runs DeepSeek for cost reasons. Each invoice arrives separately. Nobody can answer the question the finance department actually asks: which team consumed which model, and at what price.

AIHelms is aimed at that gap. The README describes it as an enterprise AI resource management platform whose stated purpose is to manage AI assets, control AI cost and measure AI value. It names three audiences explicitly. Executives get usage records, cost accounting and reports. Administrators get a console where models are onboarded, identities are issued and budgets are set. Employees get one AI identity that works across any client they choose.

The distinguishing idea is the two-track pricing model. External cost is what the upstream vendor charges. Internal settlement price is what the company bills a department. The README states these are accounted separately, so a company can pass cost through at cost or add a margin. That is a finance construct, not a proxy feature, and it is the reason the project exists rather than being another LiteLLM wrapper.

It is not for a solo developer who wants a cheaper way to call GPT. It is for an organisation with a procurement process, a chart of accounts and an IT administrator who has to justify the AI line item.

How the gateway, the ledger and the console fit together

The architecture is visible in the repository layout and the compose file. AIHelms does not implement model proxying itself. It ships LiteLLM as a service, pinned in docker-compose.yml to ghcr.io/berriai/litellm:v1.93.0, running with STORE_MODEL_IN_DB set to True and reading its configuration from ./docker/litellm/litellm.yaml mounted at /app/config.yaml. LiteLLM listens on port 4000 inside the compose network and is the component that actually speaks to OpenAI, Azure, Claude, DeepSeek and the others.

Around that sits the AIHelms application, a Python 3.11 FastAPI backend with Celery workers, a Vue 3.4 and TypeScript frontend split into admin and web packages, PostgreSQL 16 for persistence and Redis 7 for sessions, rate limiting and caching. The frontend build is a separate stage in the Dockerfile, which compiles the shared package first and then the admin and web bundles with Vite.

The data flow runs in one direction for requests and another for accounting. A client authenticates with the key AIHelms issued to an employee and sends an OpenAI- or Anthropic-shaped request. LiteLLM routes it to the upstream deployment. The usage record and the cost computation land in PostgreSQL, where the platform attributes them to a person, a department, a project and a model. The admin console and the user-facing AI Hub both read from that same store, which is why the budget a user sees on their own page and the number an administrator sees in the cost report come from one source.

Two details in the compose file matter operationally. The database service applies ./docker/db/init.sql on first start through the postgres entrypoint, and both PostgreSQL and Redis define healthchecks, so the dependency ordering is expressed rather than assumed. The LiteLLM container is attached to both an internal and an external network, which is how external AI clients reach port 4000 while the database stays off the public path.

Installing AIHelms with Docker Compose and issuing the first key

The README lists the prerequisites as Docker 20.10 or newer with Docker Compose v2, and a machine with at least 4 cores and 8 GB of memory. Installation is the standard clone, copy the environment template, edit it, then bring the stack up.

git clone https://github.com/beizhu-1209/AIHelms.git
cd AIHelms
cp .env.example .env
# 编辑 .env 填入密钥
docker compose up -d

The .env.example file documents what has to be filled in. POSTGRES_PASSWORD, REDIS_PASSWORD, SECRET_KEY for JWT signing and SUPER_ADMIN_PASSWORD for the initial administrator account are the obvious ones. Two are worth reading twice. LITELLM_MASTER_KEY must start with sk- and is the key used to create and manage virtual keys. LITELLM_SALT_KEY encrypts the model API keys stored in the database, and the comment in .env.example states it cannot be changed after first setup, because stored keys would no longer decrypt. Set both before the first start, not after.

POSTGRES_USER=aihelms
POSTGRES_PASSWORD=aihelms
POSTGRES_DB=aihelms
REDIS_PASSWORD=aihelms
LITELLM_MASTER_KEY=sk-your-litellm-master-key
LITELLM_SALT_KEY=your-salt-key-do-not-change-after-set
SECRET_KEY=your_jwt_secret_key_here
SUPER_ADMIN_PASSWORD=admin123

Once the containers are healthy, the README gives three addresses: the user portal at http://your-host, the admin console at http://your-host/admin, and the API documentation at http://your-host/api/docs. The default administrator is admin, with the password taken from SUPER_ADMIN_PASSWORD in .env.

The README then describes a three-step onboarding. In the admin console, open provider management and add a credential. Then open model management, create a model, associate it with that credential and publish it. Finally, on the user side, open My AI Identity, copy the key and endpoint, and paste them into whichever client you use. The endpoint the employee copies is the LiteLLM service, which is why the same key works for OpenAI-compatible and Anthropic-compatible clients.

Where AIHelms gets in the way

The most concrete limitation is licensing, and the README is unusually direct about it. AIHelms is GPL-3.0. Its own note says that if your organisation's policy does not permit GPL-3.0 software, or if you want to avoid the obligations that come with it, you should email the maintainers about a commercial licence. The bundled LiteLLM community edition is MIT, which does not change the position of the surrounding application. For a company that redistributes an internal platform to customers, or that has a blanket ban on copyleft dependencies, this is a decision to make before the first container starts, not after.

The second constraint is the irreversibility of LITELLM_SALT_KEY. There is no documented rotation path. A team that treats the .env file as a scratchpad during evaluation and then promotes the same database to production will discover this the hard way. The same applies to POSTGRES_PASSWORD: the .env.example comment states it only takes effect when the data directory is empty, and that changing it later requires running ALTER USER against the database to match.

AIHelms is also the wrong tool for a single-team setup. If one engineering group calls one provider and the bill is a single line item, the platform adds PostgreSQL, Redis, LiteLLM, Celery workers and a Vue console to maintain, in exchange for attribution nobody needs. The cost story only pays for itself when spend is split across departments or vendors.

There is a scope caveat in the README itself. The AI employee feature, listed under unified identity, is marked as in progress. The RoadMap section lists reports, AI health, sensitive information detection, A2A, context caching, policy management and file processing as planned. Those are intentions, not shipped capabilities, and a procurement decision should not lean on them.

AIHelms compared with running LiteLLM on its own

The obvious alternative is the component AIHelms already depends on: LiteLLM deployed directly, configured with litellm.yaml, backed by its own database. That gives you the proxy, virtual keys, model routing and spend tracking that LiteLLM provides, with one service to run instead of five.

The difference is what sits above the proxy. LiteLLM tracks spend against a key. AIHelms adds the organisational layer around that key: departments, projects, people, a budget per dimension, soft limits that warn and hard limits that disable, an internal settlement price separate from the vendor price, and reports that roll usage up by department and model. It also adds the AI market, where Skills and MCP servers are registered, reviewed and distributed to employees, and an admin audit log of operator actions.

A second alternative is to keep the vendor consoles and reconcile invoices in a spreadsheet. That works until the number of providers and the number of consuming teams both grow, at which point the reconciliation is manual, monthly and always behind. AIHelms replaces that with per-call attribution, which is a different order of accuracy.

The honest framing is that AIHelms is a management layer with a proxy underneath, not a proxy with a dashboard bolted on. If you want the proxy alone, LiteLLM is the smaller commitment. If the question you cannot answer is who spent what, the extra services are the point.

Maintenance cadence, release cost and the GPL-3.0 question

The repository is not archived, and the last push was on 2026-09-10, the same day release 0.1.24 was tagged. The changelog in the README shows a steady sequence through 2026: 0.1.4 in early June, 0.1.13 adding a Skill security scan in July, 0.1.19 upgrading the LiteLLM base to 1.93, 0.1.21 in August, and 0.1.24 in September. Releases arrive roughly every one to three weeks. The upgrade cost is therefore not the release itself but what each release touches. 0.1.24 changed model publication authorisation so that models are granted by department scope, and cancellation of a publication revokes the grant and invalidates approval records. That is a permissions change, and it changes who can see which model. 0.1.22 added email login on the Hub side. 0.1.19 replaced static asset hosting and upgraded the LiteLLM base image. Any of those can alter behaviour for existing users, so pinning AIHELMS_VERSION in .env and reading the release notes before pulling is the cheaper habit.

The licence position is straightforward to state and not to advise on. AIHelms is GPL-3.0, LiteLLM community edition is MIT, and the repository carries a THIRD_PARTY_NOTICES.md file for the rest. The README offers a commercial licence route by email for organisations that cannot accept GPL-3.0. Whether your distribution model triggers GPL obligations is a question for your own counsel, and the project's offer of an alternative licence is the relevant fact, not a substitute for that review.

Editorial conclusion

Adopt AIHelms if you already pay more than one model vendor and need per-department cost attribution, internal recharge pricing and a single key per employee. Do not adopt it if you only need a thin proxy in front of one provider, or if your legal team cannot accept GPL-3.0 in the stack. Before rolling it out, verify three things on your own host: that the LiteLLM master key and salt key are set to values you will never rotate, that the published model list matches the departments you expect after the 0.1.24 authorisation change, and that your PostgreSQL backup covers the pgdata volume, because pricing rules and audit records live there.

Frequently asked questions

Official sources

1. beizhu-1209/AIHelms on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases