onesystems/oneai repository overview

⁠OneAI

OpenAI-compatible AI gateway by OneSystems GmbH⁠.

OneAI sits in front of your LLM providers with a clean admin UI, customer portal, usage tracking, and an OpenAI-compatible /v1 API. One Docker image covers the HTTP API, admin UI, and optional batch worker.

⁠Editions: Community & Pro

OneAI ships as one Docker image. Without a license key the instance runs as Community. Activate a Pro key under System → License to unlock additional features.

Order or renew Pro at the shop⁠.

During license verification the following are sent:

• Public URL = ONEAI_PUBLIC_URL (full URL; localhost is allowed)
• Public IP = detected online via https://tools.onesystems.ch/api/tools/my-ip

⁠Image

docker pull onesystems/oneai:1.0.0

Tags: <version> and 1.0 (releases do not use latest).

The image includes the HTTP API, admin UI, customer portal, and the batch worker binary (serve / worker).

⁠Operating modes

Same product and image — only persistence and background jobs change.

Images and audio run synchronously without Redis. The Batch API (/v1/batches) requires Redis and a second container with command: ["worker"].

⁠Quick start

⁠Standard (App + Postgres)

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: oneai
      POSTGRES_PASSWORD: "change-me"
      POSTGRES_DB: oneai
    volumes:
      - postgres_data:/var/lib/postgresql/data

  oneai:
    image: onesystems/oneai:1.0.0
    user: "1000:1000"
    command: ["serve"]
    depends_on:
      - postgres
    environment:
      TZ: Europe/Zurich
      ONEAI_ENV: production
      ONEAI_PUBLIC_URL: https://ai.example.com
      ONEAI_MASTER_KEY: "change-me-to-a-long-random-secret!!"
      ONEAI_ADMIN_EMAIL: [email protected]
      ONEAI_ADMIN_PASSWORD: "change-me-strong-password"
      ONEAI_ADMIN_NAME: Administrator
      ONEAI_TRUSTED_PROXIES: "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
      POSTGRES_HOST: postgres
      POSTGRES_PORT: "5432"
      POSTGRES_USER: oneai
      POSTGRES_PASSWORD: "change-me"
      POSTGRES_DB: oneai
      POSTGRES_SSLMODE: disable   # use require when TLS is available
    volumes:
      - oneai_data:/data
    ports:
      - "8090:8080"

volumes:
  oneai_data:
  postgres_data:

docker compose up -d

The bootstrap admin from ONEAI_ADMIN_* is created only when no users exist. Changing those variables later does not update an existing account.

⁠Batch (Redis + worker)

1. Set ONEAI_REDIS_ENABLED=true and a strong REDIS_PASSWORD on the oneai service.
2. Start Redis (not published to the public internet).
3. Start another container from the same image with command: ["worker"]:

  redis:
    image: redis:7-alpine
    command: ["redis-server", "--requirepass", "change-me-redis"]
    volumes:
      - redis_data:/data

  oneai-worker:
    image: onesystems/oneai:1.0.0
    user: "1000:1000"
    command: ["worker"]
    depends_on:
      - redis
      - oneai
    environment:
      ONEAI_ENV: production
      ONEAI_MASTER_KEY: "same-as-server"
      ONEAI_REDIS_ENABLED: "true"
      REDIS_HOST: redis
      REDIS_PORT: "6379"
      REDIS_PASSWORD: "change-me-redis"
      POSTGRES_HOST: postgres
      POSTGRES_USER: oneai
      POSTGRES_PASSWORD: "change-me"
      POSTGRES_DB: oneai

Point the oneai service at the same Redis settings. Without Redis AUTH outside development, the app refuses to start.

⁠Container commands

docker compose exec oneai oneai help

⁠Gateway endpoints

• /v1/chat/completions, /v1/embeddings, /v1/responses
• /v1/images/generations|edits|variations
• /v1/audio/speech|transcriptions|translations
• /v1/files, /v1/batches (Batch needs Redis + worker)

Authenticate with project API keys (sk-… style) issued in the admin UI or portal.

⁠Core features

• OpenAI-compatible API — drop-in /v1 for apps that already speak the OpenAI protocol
• Providers & models — Ollama (Community); OpenAI, Anthropic, OpenAI-compatible endpoints (Pro); aliases, priorities, fallback
• Projects & API keys — per-project keys, rate limits, customer portal access
• Usage & billing (Pro) — token usage, sell prices, reports
• Provisioning (Pro) — WHMCS-oriented admin/provisioning API and system tokens (oas_…)
• Auth — local users, MFA (TOTP + recovery); OpenID Connect SSO with Pro
• Ops — health check, Prometheus metrics, audit trail, encrypted secrets (ONEAI_MASTER_KEY)

⁠Environment variables

⁠General

⁠Bootstrap admin (empty database only)

⁠Database

⁠Redis (optional, Batch API)

⁠SMTP (optional)

⁠OpenID Connect (SSO, Pro)

Configure issuer, client ID/secret (and options) in System → SSO. Redirect URI:

{ONEAI_PUBLIC_URL}/api/auth/oidc/callback

Local admin password login remains available as break-glass unless ONEAI_OIDC_ONLY=true.

⁠First steps after install

1. Open /admin/ and sign in with the bootstrap admin (or complete setup if prompted).
2. Finish MFA (TOTP) for the admin account; store recovery codes.
3. Under System → License, leave Community or activate a Pro key.
4. Add a provider and model (Community: one Ollama provider/model).
5. Create a project and API key; call /v1/chat/completions.
6. Optionally enable Redis + worker for Batch, SMTP for mail, and SSO (Pro).

⁠Production security checklist

• Set ONEAI_ENV=production and a unique ONEAI_MASTER_KEY (long random string, ≥ 32 characters). Losing the key means encrypted secrets cannot be recovered.
• Do not use Compose/dev defaults for admin password, master key, Postgres, or Redis.
• Persist /data on a volume; back up the volume and the master key together.
• Terminate TLS at a reverse proxy; set ONEAI_TRUSTED_PROXIES to your edge CIDRs.
• Prefer POSTGRES_SSLMODE=require when the database supports TLS.
• Do not publish Redis to the public internet; always set REDIS_PASSWORD when Redis is enabled.
• Rotate system tokens (oas_…) and project API keys if leaked.
• For SSO-only deployments, set ONEAI_OIDC_ONLY=true only after OIDC is configured and Pro is active.

⁠Health check

curl -fsS https://ai.example.com/api/health

A healthy response includes "status":"ok" and database connectivity (and Redis when enabled).

⁠Author

OneSystems GmbH⁠
[email protected]⁠

⁠License

© OneSystems GmbH. Distributed as container images via Docker Hub⁠.
Community edition is free to run; Pro unlocks additional features via a license key from the OneSystems shop⁠.
For OEM or special licensing, contact OneSystems GmbH⁠.