# darkplum

> Open-source private AI platform you install in your own cloud account. One chat for the whole organisation, one OpenAI-compatible endpoint, and a library of skills, tools and context, with a gateway that decides where every prompt may go. Apache License 2.0. Source: https://github.com/scalecraft-dev/darkplum

darkplum is for platform and security teams at organisations with a data-residency constraint who want their people to use AI without company knowledge leaving accounts the organisation does not control. It is installed by the customer with Terraform and `make deploy`; there is no hosted service and darkplum never receives customer data.

## What it does

- Models in three classes, by how far a prompt travels: self-hosted (vLLM or LM Studio in your own cluster), cloud-managed (AWS Bedrock under your own account, keys and audit trail) and vendor APIs (Anthropic or OpenAI through your own contract, which leave your account).
- Residency policy: the organisation sets how far a prompt may go. A fresh install permits self-hosted and cloud-managed models and refuses vendor APIs. Users and API keys can be held tighter than the organisation, never looser.
- A gateway at /v1/chat/completions that resolves aliases, refuses unknown and disabled models, enforces the residency setting and each user's or key's model allowlist, and records every request, refusals included, with the backend class that answered. Responses carry X-Darkplum-Backend-Class and X-Darkplum-Provider headers.
- Routed aliases: one model name that a classifier running in your cluster routes by intent to one of several models.
- A chat UI with streaming replies, model switching and server-side history readable only by its owner. Administrators see who, when and which model, never the text.
- A library of skills (instructions), context (reference text) and tools (MCP servers) stored in your own Postgres, private or shared across the organisation, attached to any chat on any model, exported as plain files. Tool servers must be on an administrator's host allowlist; tool credentials live in a cluster Secret, never in the database.
- Admin UI for users, API keys, models and vendor keys, routing and residency policy, activity, usage and estimated spend reconciled against vendor bills. Sign-in is local accounts or any OIDC identity provider.

## Install

Prerequisites: AWS CLI, Terraform 1.9 or later, kubectl, jq, Docker, Go.

    cd darkplum
    make cli && ./bin/darkplum doctor check --cloud aws --profile <your-profile>
    cp terraform/aws/terraform.tfvars.example terraform/aws/terraform.tfvars
    make deploy

About twenty minutes and roughly $305 a month at on-demand list price without a GPU node; 35 to 50 minutes and about $1,035 with one. For a laptop install with mocked inference and no cloud account: `make dev-up` (Docker and kind).

## Status

Early. AWS only. Expect breaking changes before 1.0. Not built yet: GCP, SAML and group-based roles, air-gapped installs, automatic upgrades, gateway rate limits and budget caps, workspaces, an organisation retention policy and supervised eDiscovery, image content and structured output.

## Links

- Repository and quick start: https://github.com/scalecraft-dev/darkplum#quick-start
- Operations guide (install, configure, expose, models, library, troubleshooting): https://github.com/scalecraft-dev/darkplum/blob/main/darkplum/README.md
- API reference (every route, policy bodies, every refusal code): https://github.com/scalecraft-dev/darkplum/blob/main/darkplum/docs/API.md
- Terraform (cloud selection, output contract, database durability): https://github.com/scalecraft-dev/darkplum/blob/main/darkplum/terraform/README.md
- Contributing: https://github.com/scalecraft-dev/darkplum/blob/main/CONTRIBUTING.md
- Security policy: https://github.com/scalecraft-dev/darkplum/blob/main/SECURITY.md
- License: https://github.com/scalecraft-dev/darkplum/blob/main/LICENSE