PIES Studio · Operations Manual

PIES Private AI

Run PIES Ultra — the AI engine behind PIES Studio — entirely on your own GPU infrastructure. Your prompts, application definitions, and data never leave your network. This manual covers installation, connecting PIES Studio, day-to-day operation, and troubleshooting.

1 · What you're installing

PIES Private AI is a single Docker container that serves the PIES Ultra v0.9 model — the single model this release ships (17B active / 400B total parameters) through an OpenAI-compatible API, plus an administration API that PIES Studio manages it through. It runs only with a valid PIES license and stores everything — model weights, your license, API keys — in one Docker volume on your server.

2 · Prerequisites

3 · Where to run it

Any machine meeting the specification above works. Four setups worth naming, in the order most organisations consider them: a server you own, a GPU rented by the hour while you evaluate, a cloud VM inside your own subscription, and — for smaller teams — an Apple Silicon Mac.

Your own NVIDIA server — the fullest version of private

PIES Private AI was built for this. The model runs on hardware you own, in a building you control, and nothing about a request — the prompt, your data, your application — leaves the room. It is the only option that can be made genuinely air-gapped, and the only one where the running cost is the electricity.

Internet access is needed once, to download the weights — and not even then if you bring them in on media, which is covered in section 7. After that the server can be disconnected entirely and the platform keeps working: the license is validated locally, not by calling home.

A rented GPU, billed by the hour

The cheapest way to stand PIES Private AI up, and the one to use while you are evaluating. Providers such as RunPod, Lambda or Vast rent GPU machines by the hour and let you stop them when you are not using them.

Install exactly as in section 4 — it is an ordinary Linux host with GPUs. What differs is the running cost: you pay per hour while it runs, and only for the volume while it is stopped. That makes it practical to run the AI during working hours and stop it overnight; the model reloads into VRAM in 10–20 minutes on the next start.

A cloud VM under your own subscription

What most organisations move to for production: the machine lives inside your tenancy, your network controls, and your compliance boundary. On Azure the relevant families are ND A100 v4 (8× A100 80 GB) and ND H100 v5 (8× H100 80 GB); AWS and Google have direct equivalents.

Reserved or committed-use pricing changes the economics substantially for a machine that runs continuously — worth pricing before choosing between hourly rental and a cloud VM.

An Apple Silicon Mac

A Mac with Apple Silicon and enough unified memory runs PIES Ultra on the same llama.cpp engine as the Docker image, using Apple's Metal GPU. It serves one request at a time and answers more slowly than a multi-GPU server, which makes it a fit for a small team or an evaluation on hardware you may already own — not for many people building at once.

Install with one command in Terminal — it downloads PIES Private AI to ~/pies-private-ai:

curl -fsSL https://github.com/pies-io/pies-studio-releases/releases/download/private-ai-mac-v0.9/install-mac.sh | bash

Then, from that folder, three commands finish the job:

cd ~/pies-private-ai
./pies-llm.sh setup                                # one-time: engine + model download
./pies-llm.sh license /path/to/pies_studio.license
./pies-llm.sh start                                # loads the model, waits until ready

The same license rules apply as on a server: without a valid pies_studio.license the service starts but refuses AI requests.

Lite option: add --lite to both commands to run PIES Ultra Lite instead — a smaller model (~65 GB download, 96 GB+ unified memory) that loads in about two minutes and answers faster, at lower build quality. It suits evaluation and smaller Macs; use full PIES Ultra for real work.

./pies-llm.sh setup --lite
./pies-llm.sh start --lite

All commands are safe to re-run — setup skips what is already done and a stopped download resumes where it left off. ./pies-llm.sh status shows health, and PIES Studio connects to port 8000 exactly as with the Docker install (section 5).

4 · Install

Run everything below on the GPU server, as a user who can run docker. Four steps; the installer does the checking.

1. Get the pies-llm command

   The management CLI ships inside the container image — no separate download:

   docker run --rm --entrypoint cat ghcr.io/pies-io/pies-llm:vllm /app/pies-llm-ctl.sh \
     | sudo tee /usr/local/bin/pies-llm >/dev/null && sudo chmod +x /usr/local/bin/pies-llm

2. Run the installer

   pies-llm install /path/to/pies_studio.license

   It checks your GPUs, free disk and Docker GPU access, pulls the image, stores the license, generates your admin key and starts the service. If a prerequisite is missing it stops and says what to fix — nothing large is downloaded until the checks pass.

   The installer prints your admin API key — save it. It is also kept in ~/.pies-llm/config.

3. Wait for the one-time model download

   pies-llm logs -f

   First start downloads 216 GB of model weights into the pies-llm-models volume, then loads them into VRAM. The service is deliberately quiet until the engine is ready — a port that does not answer yet is normal, not a hang.

   Stage	Typical time
   Weights download (once, cached on the volume)	30–90 min
   Engine load into VRAM (every start)	10–20 min
   Later starts (weights already present)	10–20 min total

   pies-llm status reports model_loaded: false until the engine finishes; then it shows backend: vllm and your licence details.

4. Verify, then connect PIES Studio

   pies-llm status   # model_loaded: true, backend: vllm, license valid

   Open port 8000 to PIES Studio, then in Studio go to Administration → AI Settings → PIES Private AI and enter:

   • URL — http://<your-server>:8000
   • API key — the admin key from step 2

   Use Test connection, then check the Private LLM tab shows the model Online. Run the CLI on the server itself — it talks to the service on localhost.

5 · Day-to-day operation

API keys: admin vs. inference

The admin key (created at install) opens everything and is what PIES Studio uses. Inference keys (pies-llm key create) can only run AI requests — hand them to individual apps or teams, and revoke any one of them at any time without affecting the others.

6 · License

Where the file comes from

PIES issues you a single file, pies_studio.license — either attached to an email or downloaded from the setup link your account manager sends. Copy it to the GPU server and point the installer at it. It is stored on the pies-llm-models volume beside the model weights, so it survives restarts, container recreation and upgrades; the copy you were sent is not needed afterwards.

Checking and renewing

pies-llm license show                            # org, tier, expiry, days remaining
pies-llm license install ~/pies_studio.license   # install or renew

Renewal needs no restart — the file is re-checked within a minute. The new license is validated before it replaces the old one, so a wrong or corrupt file is rejected and your running license is left untouched. pies-llm license show warns when 30 days or fewer remain.

The license is checked continuously — signature, expiry, and status. When it expires or is removed, AI requests return HTTP 403 with the exact reason, while health and administration stay reachable so you can always see why.

7 · Air-gapped installation (no internet)

The only step that needs the internet is the one-time weights download. Do it on any connected machine, carry the result across, and import it.

1 · On a connected machine

Get the weights (216 GB). This is a public Hugging Face repository — no PIES account or token is involved. Either route must end with a folder named exactly Llama-4-Maverick-17B-128E-Instruct-quantized.w4a16.

Option A — command line. Resumable, and strongly preferred at this size: an interrupted download continues where it left off, just run it again.

pip install huggingface_hub
huggingface-cli download RedHatAI/Llama-4-Maverick-17B-128E-Instruct-quantized.w4a16 \
  --local-dir Llama-4-Maverick-17B-128E-Instruct-quantized.w4a16

Option B — manual browser download, if the machine has no Python or your policy requires a human-reviewed download. Open the repository file list, create a folder named Llama-4-Maverick-17B-128E-Instruct-quantized.w4a16, and save every file into it:

Keep the structure flat — no sub-folders, no renaming. Browser downloads have no resume and no integrity check, which is why Option A is preferred.

Either way, copy the whole directory onto your approved media — a missing shard is the usual air-gap failure, and import-weights checks for exactly that on the other side before it copies anything. Take the container image the same way:

docker pull ghcr.io/pies-io/pies-llm:vllm
docker save ghcr.io/pies-io/pies-llm:vllm | gzip > pies-llm-vllm.tar.gz

2 · On the air-gapped server

docker load < pies-llm-vllm.tar.gz
pies-llm import-weights /media/transfer/Llama-4-Maverick-17B-128E-Instruct-quantized.w4a16
pies-llm start   # finds the weights on the volume — never touches the network

import-weights checks the directory is a complete snapshot before copying 216 GB, and stores it on the pies-llm-models volume under the exact name the service looks for — so it works even if your media folder is named something else.

After this, nothing in the product requires egress — prompts, data, and license checks all stay on the server.

8 · HTTPS / TLS

Out of the box the service speaks plain HTTP on port 8000 — appropriate on localhost, behind a TLS-terminating proxy (nginx, caddy, a cloud load balancer), or on an isolated network. If the API key crosses a network you don't fully trust, serve HTTPS directly by mounting a PEM certificate and key:

docker run ... \
  -v /etc/pies-llm/certs:/certs:ro \
  -e PIES_LLM_SSL_CERT=/certs/fullchain.pem \
  -e PIES_LLM_SSL_KEY=/certs/privkey.pem \
  ghcr.io/pies-io/pies-llm:vllm

Then use https://<server>:8000 in PIES Studio.

9 · Troubleshooting