Allotment AI gives every team and person an enforced AI budget — self-hosted, so nothing goes outbound except the AI providers you enable and a monthly license check (never employee data).
Per-person budgets and hard enforcement cover API and CLI traffic routed through your self-hosted gateway — Claude Code, Codex, and your own apps. Seat products used in a browser (ChatGPT / Claude Enterprise) are governed per team, and the console shows the coverage %: exactly what share of your invoice each covers.
CADDY_HTTP_PORT=8080 CADDY_HTTPS_PORT=8443 CADDY_GW_PORT=9443 ./install.shlocalhost| console | the app — budgets, pools, dashboards |
| postgres | the ledger (all your data, in a Docker volume) |
| gateway | the AI gateway — starts in safe mock mode |
| worker · redis | background jobs · cache |
| caddy | HTTPS — console on 443, gateway on 8443 |
🔐 The console requires sign-in — company SSO (Microsoft Entra / OpenID Connect) and/or a break-glass admin password. See "Who can open the console?" below.
curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.6.1.tar.gz curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.6.1.tar.gz.sha256 sha256sum -c tokenshare-install-v0.6.1.tar.gz.sha256
tar xzf tokenshare-install-v0.6.1.tar.gz cd tokenshare-install/install ./install.sh
https://YOUR-HOST/ — you're in. License & updates at /?screen=license. installed ✓
A public DNS name (resolves to this server, ports 80/443 reachable) → a real HTTPS certificate is fetched automatically.
An internal-only name (no public DNS) → edit Caddyfile, un-comment tls internal in both blocks, then docker compose up -d. HTTPS is then signed by the proxy’s own root CA, so there is a second step: turn on Settings → Employee machine setup → Internal hostname · private CA and every machine-setup file installs that certificate too — the console hands it out, and nobody is ever asked to turn certificate checking off.
localhost → works immediately; your browser shows a one-time certificate warning — expected.
Copy this prompt into your AI assistant. If it can run commands on your server (Claude Code, Cursor, an agent) it does the whole install; in a chat (Claude, ChatGPT) it walks you through every step.
Help me install Allotment AI — a self-hosted AI-credit management app that runs entirely on my own server with Docker. Nothing goes outbound except the AI providers I enable and a monthly license check (no employee data). Ask me before anything destructive.
If you can run shell commands on my Linux server, do the install and explain each step, pausing for anything you need from me. If you can't run commands, give me exact copy-paste commands and walk me through them.
1. Check prerequisites: Docker + Docker Compose v2 installed and running, and host ports 80/443/8443 free. If Docker is missing: https://docs.docker.com/get-docker/
2. Download and verify the bundle:
curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.6.1.tar.gz
curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.6.1.tar.gz.sha256
sha256sum -c tokenshare-install-v0.6.1.tar.gz.sha256
3. Extract and run the installer:
tar xzf tokenshare-install-v0.6.1.tar.gz
cd tokenshare-install/install
./install.sh
4. The installer generates all secrets and asks me three questions:
- a license key (a free 60-day full-product ROI Pilot at https://allotmentai.com/signup — or blank for free mode, I can add one later in the console)
- the hostname for the console (or "localhost" to start; internal-only names need `tls internal` un-commented in the Caddyfile)
- whether to load a sample org (yes = explore immediately)
It then pulls the prebuilt images and starts seven containers (Postgres, Redis, the console, a background worker, the AI gateway in mock mode, an HTTPS proxy, and a four-line sidecar that exports the private root CA on internal-hostname installs) and runs the database migrations.
5. When it finishes, confirm the console is up at https://MY-HOST/ and the license screen at https://MY-HOST/?screen=license
Then remind me of the go-live step for later: add my OpenAI/Anthropic API keys to .env, set LAB_GATEWAY=litellm, run "docker compose up -d", then mint keys for everyone from the console's Gateway Keys screen ("Mint for all seat-holders") — employee tools then use https://MY-HOST:<the gateway port this install published> (CADDY_GW_PORT, 8443 unless I changed it — install.sh prints the exact URL, and the console arrives pre-filled with it)
If anything fails, run "docker compose logs -f console", read the error, and help me fix it.
The gateway starts in mock mode — the console fully works, nothing real is spent. When you're ready to route your company's actual AI traffic (this is where enforcement and attribution happen), two steps from the install/ directory:
# 1 — your org's provider keys (kept on YOUR server only) + flip the gateway to live nano .env # OPENAI_API_KEY=sk-… ANTHROPIC_API_KEY=sk-… LAB_GATEWAY=litellm docker compose up -d # 2 — mint a virtual key for every seat-holder (they never see raw provider keys): # click "Mint for all seat-holders" in the console's Gateway Keys screen, or headless — docker compose exec console node --import tsx lab/web.ts --mint-all-seats
Employee tools (Claude Code, Codex…) then talk to https://YOUR-HOST:<your gateway port> — whatever CADDY_GW_PORT published, 8443 unless you changed it — with their own personal key, never a raw provider key. Set that URL once in Settings → Employee machine setup, and each person gets a one-click setup file from My Wallet (or push the env vars via GPO / Intune / Jamf — the exact vars are in the console).
/?screen=licenseYour org tree: explore with the sample org now. On a production install (you answered “no” to the sample org) the console opens on a first-run setup page — name your organization, add your people with the single form or by pasting a CSV roster (email,name,title,manager_email,org_unit_path), then record the credits you purchased from each provider. Re-importing the same roster updates people instead of duplicating them. A nightly Microsoft Entra directory sync is available too — it runs only once you set GRAPH_TENANT_ID, GRAPH_CLIENT_ID and GRAPH_CLIENT_SECRET (one read-only app registration), and does nothing at all until then. The CSV roster is still the fastest way to start, and because the email is the key you can add the sync later without duplicating anybody.
The console tells the admin when a new version is out (License → Software updates, ordered by importance). From the install/ directory:
./update.sh # fetch the latest, verify checksum, rebuild, restart — your data survives ./update.sh --check # just show what's new — changes nothing ./update.sh v0.6.1 # offline: pre-download the bundle + .sha256 into install/ first
Your .env is never touched and the database lives in Docker volumes — an update only replaces the application. Your edits to the two files you are meant to change, Caddyfile and litellm-config.yaml, are kept: an edited file is left exactly as you set it and the release's own copy lands beside it as <name>.new to review.
For platform teams: ship it through your own pipeline, into your own cluster — pulling our public image, or one you built yourself. The Helm chart lives in the bundle under deploy/helm; ready-to-edit CI and GitOps manifests under deploy/ci and deploy/cd. Three workloads: the console, the AI gateway (autoscaled), and the background worker.
kubectl & helm pointed at itghcr.io/allotment-ai/console (multi-arch, amd64+arm64), no registry of your own needed. Prefer to run only what you build? Building it from the bundled source into your own registry is a supported option, not the only path — point image.console.repository at your copy.metrics-server (the gateway autoscaler needs it)Help me deploy Allotment AI — a self-hosted AI-credit management app — to my own Kubernetes cluster using its Helm chart. It runs entirely inside my cluster; the only outbound calls are the AI providers and a monthly license check (no employee data ever leaves). Confirm my kubectl context first, and ask me before anything destructive.
If you can run shell commands (kubectl, helm, docker), do the deploy step by step, pausing for anything you need from me. Otherwise give me exact copy-paste commands.
0. Check what I have: current kube context (kubectl config current-context), an ingress controller + TLS, and metrics-server (needed for the gateway autoscaler). Tell me what's missing before continuing. I do NOT need a registry of my own unless I choose to build the image myself.
1. Get the bundle (it contains the Helm chart at deploy/helm/tokenshare and the image Dockerfile at install/Dockerfile.console):
curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.6.1.tar.gz
curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.6.1.tar.gz.sha256
sha256sum -c tokenshare-install-v0.6.1.tar.gz.sha256 && tar xzf tokenshare-install-v0.6.1.tar.gz && cd tokenshare-install
2. Nothing to build: the chart already points at the official public console image ghcr.io/allotment-ai/console (multi-arch, amd64+arm64) — no registry of your own needed. ONLY if my policy is to run just what I build myself, build it from the bundle and push it to my registry, then set image.console.repository/.tag to that:
docker build -f install/Dockerfile.console -t MY-REGISTRY/allotment-console:0.6.1 .
docker push MY-REGISTRY/allotment-console:0.6.1
3. Create the namespace and the secret. A license is a free 60-day full-product ROI Pilot at https://allotmentai.com/signup (or leave TOKENSHARE_LICENSE blank for free mode). Ask me for each value:
kubectl create namespace allotment
kubectl create secret generic allotment-secrets -n allotment \
--from-literal=POSTGRES_PASSWORD=... --from-literal=REDIS_PASSWORD=... \
--from-literal=LITELLM_MASTER_KEY=sk-... --from-literal=LITELLM_DB_PASSWORD=... \
--from-literal=ALLOTMENT_KEK="$(openssl rand -base64 32)" --from-literal=TOKENSHARE_LICENSE=TS1.... \
--from-literal=OPENAI_API_KEY=... --from-literal=ANTHROPIC_API_KEY=...
(LITELLM_DB_PASSWORD is the AI gateway's OWN database role — it never touches the ledger database.
ALLOTMENT_KEK encrypts every employee's gateway key at rest: back it up with the DB password,
because losing it means re-minting every key.)
4. Edit deploy/helm/example-values.yaml (the ingress host + TLS, gateway min/maxReplicas, worker.enabled, and postgresql.enabled — plus image.console.repository ONLY if I built my own image in step 2), then deploy:
helm upgrade --install allotment deploy/helm/tokenshare -n allotment \
-f deploy/helm/example-values.yaml --set secrets.existingSecret=allotment-secrets --wait
5. Verify: kubectl get pods -n allotment shows console, gateway, worker, postgres and redis Ready; the ingress serves HTTPS; the console opens and /?screen=license shows my license. Prefer GitOps over step 4? use the manifests in deploy/cd (Argo CD or Flux).
If anything fails: kubectl logs / kubectl describe pod / helm status allotment -n allotment, read the error, and help me fix it.
curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.6.1.tar.gz curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.6.1.tar.gz.sha256 sha256sum -c tokenshare-install-v0.6.1.tar.gz.sha256 tar xzf tokenshare-install-v0.6.1.tar.gz && cd tokenshare-install
The chart already runs the official public console image ghcr.io/allotment-ai/console (multi-arch, amd64+arm64) — no registry of your own needed. Building it yourself from the bundled source and running that instead is a supported option for air-gapped or registry-policy clusters, not the only path; then set image.console.repository / .tag to your copy in step 4.
docker build -f install/Dockerfile.console -t MY-REGISTRY/allotment-console:0.6.1 . docker push MY-REGISTRY/allotment-console:0.6.1
kubectl create namespace allotment kubectl create secret generic allotment-secrets -n allotment \ --from-literal=POSTGRES_PASSWORD='<strong>' \ --from-literal=REDIS_PASSWORD='<strong>' \ --from-literal=LITELLM_MASTER_KEY='sk-<strong>' \ --from-literal=LITELLM_DB_PASSWORD='<strong>' \ --from-literal=ALLOTMENT_KEK="$(openssl rand -base64 32)" \ --from-literal=TOKENSHARE_LICENSE='TS1.<your-license>' \ --from-literal=OPENAI_API_KEY='' \ --from-literal=ANTHROPIC_API_KEY='' # license '' = free mode · provider keys '' = evaluate without the live gateway # LITELLM_DB_PASSWORD = the gateway's OWN database role (it never touches the ledger database) # ALLOTMENT_KEK encrypts every employee's gateway key at rest — BACK IT UP: losing it means re-minting every key
deploy/helm/example-values.yaml, then deploySet three things in the file: the console ingress host + TLS · postgresql.enabled: true (or your managed DB URL) · and if employee laptops connect from outside the cluster, enable the gateway ingress with its own hostname (e.g. ai-gw.yourco.com). A fourth, image.console.repository, only if you built your own image in step 2.
helm upgrade --install allotment deploy/helm/tokenshare \ --namespace allotment -f deploy/helm/example-values.yaml \ --set secrets.existingSecret=allotment-secrets --wait
kubectl get pods -n allotment → console, gateway, worker, postgres, redis all Ready/?screen=license shows your plan (free mode is fine)Prefer GitOps for step 4? The same deploy as an Argo CD / Flux app is below — full files in deploy/cd/.
name: allotment-deploy
on: { push: { branches: [main] } }
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: docker/build-push-action@v6
with:
context: .
file: install/Dockerfile.console
push: true
tags: ghcr.io/your-org/allotment-console:${{ github.sha }}
- run: |
helm upgrade --install allotment deploy/helm/tokenshare -n allotment \
--set image.console.repository=ghcr.io/your-org/allotment-console \
--set image.console.tag=${{ github.sha }} \
--set secrets.existingSecret=allotment-secrets --waitFull workflow + a GitLab CI variant ship in deploy/ci/.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata: { name: allotment, namespace: argocd }
spec:
source:
repoURL: https://git.your-org/allotment.git
path: deploy/helm/tokenshare
targetRevision: main
helm: { valueFiles: [../example-values.yaml] }
destination:
server: https://kubernetes.default.svc
namespace: allotment
syncPolicy: { automated: { prune: true, selfHeal: true } }A Flux HelmRelease variant ships in deploy/cd/.
The app + database run on your server. Outbound, only: the AI providers you enable (your own keys), allotmentai.com (bundle downloads + updates) and cp.allotmentai.com (monthly license check + update availability — sends your license key, an anonymous install id, a version and an aggregate user count; never names, emails or usage detail — the console shows you exactly what's sent). During the first build the server also pulls from Docker Hub, ghcr.io and registry.npmjs.org, and acme-v02.api.letsencrypt.org issues the HTTPS certificate for a public hostname. Nothing inbound is required except ports 80/443 if you want an automatic public certificate.
The console requires authentication. Recommended: company SSO — Microsoft Entra ID or any OpenID Connect provider (Okta, Auth0, Google Workspace). People sign in with their work account (authorization-code + PKCE, the ID token is verified); admins and finance are an explicit allowlist, everyone else is mapped from your directory. Set CONSOLE_OIDC_ISSUER, CONSOLE_OIDC_CLIENT_ID, CONSOLE_OIDC_CLIENT_SECRET and CONSOLE_OIDC_ADMIN_EMAILS in .env — the 5-minute Entra app-registration walkthrough is in docs/oidc-sso.md. A shared admin password (CONSOLE_ADMIN_SECRET) also works on its own, and stays as a break-glass login for when SSO is down. Defense in depth: still keep the console on your network / VPN.
Free (no license, or expired) = full credit management plus the AI gateway: managed per-user keys, hard budget enforcement (requests stop the moment a budget hits zero) and per-user attribution. A license adds the savings layer — response cache and smart routing, automatic return of idle credits, reconciliation against provider invoices, chargeback reports and insights. Signing up gets a free 60-day full-product ROI Pilot, once per company. Full comparison on the pricing page.
Backups: ./backup.sh in install/ takes the whole snapshot — a pg_dump of both databases (the ledger and the gateway's own), the console's vkeys volume and a mode-600 copy of your .env, with checksums, into ./backups/ plus one .tar.gz to carry off the box. Nothing is stopped while it runs, ./update.sh takes one automatically before every update, and ./restore.sh <snapshot> puts it back (it makes you type RESTORE first). A snapshot holds your ledger and your secrets — keep it off this machine. Someone leaves: Seats → ⨯ Offboard — one action reclaims every provider seat back to the company pools, revokes their gateway key so their tools stop immediately, and refuses their SSO sign-in. Nothing is deleted; the ledger is append-only.
Yes, anytime — paste it in the console (/?screen=license → Apply). No reinstall, takes effect immediately.
The license verifies offline (signed), and updates can be applied offline (./update.sh vX.Y.Z with a pre-downloaded bundle). Ask us for a long-dated offline license: support@allotmentai.com.
Run docker compose logs -f console from the install/ folder and read the error — or paste it into the AI prompt above and let your assistant fix it. Ports 80/443 already taken by another web server is the most common hiccup — free them, or install on alternate ports: CADDY_HTTP_PORT=8080 CADDY_HTTPS_PORT=8443 CADDY_GW_PORT=9443 ./install.sh. Once installed, bugs go straight to us from the console: License → Report a problem.