Self-hosted install

Run Allotment AI on your own servers in ~10 minutes.

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).

No signup needed — install first, add a license key anytime.

Before you start

  • A Linux server — ~2 vCPU / 4 GB RAM / 5 GB disk
  • Docker + Docker Compose v2 (get Docker)
  • Ports 80, 443, 8443 free on that host (the bundle brings its own HTTPS proxy)
  • A hostname — or just start with localhost
  • Optional: your company's OpenAI / Anthropic API keys — only needed later, to route real traffic
  • Optional: a license — not required; free mode works, signup = 3 months of everything
  • Optional (recommended for teams): SSO — your Microsoft Entra / OIDC details, so people sign in with their work account (see below)

What lands on your server

consolethe app — budgets, pools, dashboards
postgresthe ledger (all your data, in a Docker volume)
gatewaythe AI gateway — starts in safe mock mode
worker · redisbackground jobs · cache
caddyHTTPS — 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.

The install

Three commands, three questions

Download & verify 
curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.5.5.tar.gz
curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.5.5.tar.gz.sha256
sha256sum -c tokenshare-install-v0.5.5.tar.gz.sha256
Extract & run the installer 
tar xzf tokenshare-install-v0.5.5.tar.gz
cd tokenshare-install/install
./install.sh
Answer three short questions
License key — press Enter for free mode (signup gets 3 months of everything; you can paste a key later in the console).  Hostname — see "which hostname?" below.  Load a sample org? — say yes to explore; say no for a production install. All passwords and secrets are generated for you.
Open the console
https://YOUR-HOST/ — you're in. License & updates at /?screen=license. installed ✓
Which hostname should I give it?

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.
localhost → works immediately; your browser shows a one-time certificate warning — expected.

🤖 Prefer not to touch a terminal?

Let your AI assistant install it

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.5.5.tar.gz
   curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.5.5.tar.gz.sha256
   sha256sum -c tokenshare-install-v0.5.5.tar.gz.sha256

3. Extract and run the installer:
   tar xzf tokenshare-install-v0.5.5.tar.gz
   cd tokenshare-install/install
   ./install.sh

4. The installer generates all secrets and asks me three questions:
   - a license key (3 months full & free 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 builds and starts six containers (Postgres, Redis, the console, a background worker, the AI gateway in mock mode, and an HTTPS proxy) 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, run "docker compose exec console npm run lab:keys", set LAB_GATEWAY=litellm, and "docker compose up -d" — employee tools then use https://MY-HOST:8443
   If anything fails, run "docker compose logs -f console", read the error, and help me fix it.
ClaudeClaude CodeChatGPTCursorGeminiany terminal-capable agent
The step that makes it real

Go live: connect your AI providers

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), three steps from the install/ directory:

# 1 — your org's provider keys (kept on YOUR server only)
nano .env                        # fill in:  OPENAI_API_KEY=sk-…   ANTHROPIC_API_KEY=sk-…
docker compose up -d

# 2 — mint per-user virtual keys (seat-holders only — employees never see raw provider keys)
docker compose exec console npm run lab:keys

# 3 — flip the gateway from mock to live
nano .env                        # change:  LAB_GATEWAY=mock  →  LAB_GATEWAY=litellm
docker compose up -d

Employee tools (Claude Code, Codex…) then talk to https://YOUR-HOST:8443 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).

You're installed — now what?

Your first 10 minutes in the console

Look around
If you loaded the sample org: a full company with pools, budgets and seats is ready to play with — nothing is real, break anything.
Check /?screen=license
Your plan (free mode is fine), Software updates (we tell you when a new version is out, security fixes first), and 🐞 Report a problem — reaches us directly, free plan included.
Set real budgets
Pools → your company pool → allocate down to departments and teams. Budgets without the live gateway are advisory; after go-live they're enforced — requests stop when a wallet hits zero.
Give people keys
Gateway Keys screen → mint a key per person → each employee sets up their machine with one click from My Wallet.

Your org tree: explore with the sample org now; connecting your real directory (Microsoft Entra) is optional and can come later — you can also manage the tree manually.

Staying current

Updating is one command

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.5.5     # 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.

🏗 Deploying to Kubernetes instead? Helm chart + CI/GitOps templates included

For platform teams: ship it through your own pipeline — your registry, your cluster. 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.

What you need

  • A cluster + kubectl & helm pointed at it
  • A container registry you can push to (the image is built from the bundle — there is no public image, by design: you run only what you built)
  • An ingress controller + TLS for the console hostname
  • metrics-server (the gateway autoscaler needs it)
🤖 The easy way

Deploy to Kubernetes with AI

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), a container registry I can push to, an ingress controller + TLS, and metrics-server (needed for the gateway autoscaler). Tell me what's missing before continuing.

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.5.5.tar.gz
   curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.5.5.tar.gz.sha256
   sha256sum -c tokenshare-install-v0.5.5.tar.gz.sha256 && tar xzf tokenshare-install-v0.5.5.tar.gz && cd tokenshare-install

2. Build and push the console image to MY registry (replace MY-REGISTRY; keep the tag = the bundle version):
   docker build -f install/Dockerfile.console -t MY-REGISTRY/allotment-console:0.5.5 .
   docker push MY-REGISTRY/allotment-console:0.5.5

3. Create the namespace and the secret. A license is free for 3 months (full product) 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=TOKENSHARE_LICENSE=TS1.... \
     --from-literal=OPENAI_API_KEY=... --from-literal=ANTHROPIC_API_KEY=...

4. Edit deploy/helm/example-values.yaml (set image.console.repository to MY-REGISTRY/allotment-console, the ingress host + TLS, gateway min/maxReplicas, worker.enabled, and postgresql.enabled), 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.
Claude CodeCursorClaudeChatGPTany kubectl-capable agent

1 · Get the bundle

curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.5.5.tar.gz
curl -fsSLO https://allotmentai.com/downloads/tokenshare-install-v0.5.5.tar.gz.sha256
sha256sum -c tokenshare-install-v0.5.5.tar.gz.sha256
tar xzf tokenshare-install-v0.5.5.tar.gz && cd tokenshare-install

2 · Build the console image & push it to YOUR registry

docker build -f install/Dockerfile.console -t MY-REGISTRY/allotment-console:0.5.5 .
docker push MY-REGISTRY/allotment-console:0.5.5

3 · Create the secret once

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=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

4 · Edit deploy/helm/example-values.yaml, then deploy

Set four things in the file: image.console.repository = your registry image · 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).

helm upgrade --install allotment deploy/helm/tokenshare \
  --namespace allotment -f deploy/helm/example-values.yaml \
  --set secrets.existingSecret=allotment-secrets --wait

5 · Verify & go live

  • kubectl get pods -n allotment → console, gateway, worker, postgres, redis all Ready
  • Open the console through your ingress → /?screen=license shows your plan (free mode is fine)
  • Employee tools talk to the gateway hostname you exposed in step 4 — set it once in Settings → Employee machine setup → Public gateway URL, then mint keys on the Gateway Keys screen

Prefer GitOps for step 4? The same deploy as an Argo CD / Flux app is below — full files in deploy/cd/.

CI — build & deploy (GitHub Actions)

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 --wait

Full workflow + a GitLab CI variant ship in deploy/ci/.

CD — GitOps (Argo CD)

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/.

Good to know

Is my data safe? What leaves my network?

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.

Who can open the console? (SSO / login)

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 vs licensed?

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 3 months of everything free, once per company. Full comparison on the pricing page.

Can I add a license later?

Yes, anytime — paste it in the console (/?screen=license → Apply). No reinstall, takes effect immediately.

No internet on the server (air-gapped)?

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@aisite.co.il.

Something failed

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 use a different host. Once installed, bugs go straight to us from the console: License → Report a problem.