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 model PIES ships and certifies (17B active / 400B total parameters) — through an OpenAI-compatible API, plus an administration API that PIES Studio manages it through. You can also run models of your own alongside it (section 9). 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.

How you install depends on what the provider hands you. A rented virtual machine is an ordinary Linux host with GPUs: install exactly as in section 4. A rented GPU pod (RunPod, Vast and similar) is itself a container, with no Docker inside it, so the installer cannot run there. Use the pod setup below instead. What differs from your own server 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.

GPU pods (RunPod, Vast and similar)

On a pod you do not run pies-llm install. You give the provider the PIES image and a few settings, and the pod runs it directly. Everything the installer would have done is in this table.

On first start the pod writes the license onto the volume, downloads the weights to it, and loads the engine. Because both live on the volume, later starts reuse them. Then connect PIES Studio as in section 4, using the provider's HTTPS address for port 8000 and your admin key.

PIES_LLM_LICENSE_B64 is read only when the volume holds no license yet (/app/models/pies_studio.license). It never replaces one that is already there, so changing the pod setting does not renew a license. To renew on a pod, open the pod's terminal and replace /app/models/pies_studio.license with the new file; it is re-checked within a minute, no restart needed.

PIES Ultra Lite on a single GPU

For evaluation, or to check networking, the license and the Studio connection before renting 256 GB of VRAM, run PIES Ultra Lite instead. It is a smaller model (~65 GB of weights) that fits on one GPU and is ready about 2½ minutes after the pod is created. It answers fast but builds noticeably less well than PIES Ultra, so use it to try the platform, not for real work. It uses the llama.cpp image, on a pod or a server alike:

Studio shows it as PIES Ultra Lite (dev). Everything else — connecting Studio, keys, the license — works exactly as for PIES Ultra.

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 runs PIES Ultra Lite 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. PIES Ultra itself belongs on a GPU server: on a Mac the launcher runs Lite and refuses PIES Ultra unless you override it deliberately (below).

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

The model loads in about two minutes and appears in Studio as PIES Ultra Lite (dev). It builds less well than PIES Ultra on a GPU server; use the Mac for evaluation and small teams.

PIES Ultra on a Mac is possible only as a deliberate override, on a Mac with 256 GB+ unified memory and ~250 GB free disk (a ~200 GB download), with nothing else loaded first:

./pies-llm.sh setup --ultra
PIES_LLM_ALLOW_ULTRA_MAC=1 ./pies-llm.sh start --ultra

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 4, step 4).

Updating an existing Mac install

Run the installer again with --upgrade. It replaces the program only — your models, training data, adapters, API keys and license are left exactly as they are, so no weights are downloaded twice:

curl -fsSL https://github.com/pies-io/pies-studio-releases/releases/download/private-ai-mac-v0.9.1/install-mac.sh | bash -s -- --upgrade
cd ~/pies-private-ai && ./pies-llm.sh restart

Without --upgrade the installer refuses to touch an existing folder, so re-running the plain install line can never overwrite a working service. The version now serving is shown in Private LLM → Manage, which is the quickest way to confirm an upgrade took.

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 open PIES AI → AI Settings (an administrator's view) and, under Providers, find the PIES Private AI row and enter:

   • Service URL — http://<your-server>:8000 (on a GPU pod, the provider's HTTPS address for port 8000)
   • API key — the admin key from step 2

   Press Connect, then Test connection, and check the Private LLM tab shows the model Online. The URL and key apply to the whole install. Run the CLI on the server itself — it talks to the service on localhost.

   Connecting makes the model available; which requests actually use it is decided by your AI governance policies — see section 10.

5 · Day-to-day operation

Managing the service from PIES Studio

Most day-to-day operation no longer needs a terminal. PIES AI → Private LLM → Manage works against whichever host Studio is connected to and shows:

Starting and stopping the service itself stays on the host, for the obvious reason: when it is down there is nothing for Studio to talk to. Use pies-llm start there.

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.

API keys on an Apple Silicon Mac

The Mac install manages keys with the same commands, through ./pies-llm.sh. The admin key is created automatically the first time you run setup or start — it is printed once and kept in ~/.pies/pies-llm.env:

./pies-llm.sh key show                # the admin key — what PIES Studio connects with
./pies-llm.sh key create <name>       # mint an inference-only key (shown once)
./pies-llm.sh key list                # list minted keys (masked)
./pies-llm.sh key delete <id>         # revoke one

Admin vs. inference works exactly as on a server: the admin key opens everything and belongs in PIES Studio's AI Settings; inference keys can only run AI requests and can be revoked individually at any time.

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 · Bring your own model

PIES Private AI runs models beyond PIES Ultra. The Private LLM tab has an Upload Your Own tile: bring any GGUF model — from Hugging Face or your own fine-tune — and the platform handles the rest, with no configuration.

Uploaded models also join the fine-tuning loop: verified wins from their builds are collected, and an adapter is only promoted to serving if it beats the model's own certified baseline.

Seed training data ships with every install. The file data/collected/seed_mcp_pack.jsonl is built from the release's PIES Studio MCP training pack — the canonical widget, step, event and process shapes — and stamped with the pack version and hash. It is copied into the training data directory on first start only if no seed file is there; your own training files are never overwritten or removed. Its examples are counted in the training data totals, and every fine-tuning job trains on it together with your own data, so even a fresh install has a starting corpus. To train without it, send "include_seed": false with the training request; if the file is missing, training carries on without it. To take a newer release's seed, delete the file and restart.

10 · Using PIES Private AI in PIES Studio

Once connected, PIES Private AI is one of the providers Studio can use. Your AI governance policies decide which requests go to it — the full rules are in the user manual's AI governance chapter. The parts that matter for Private AI:

When the Private AI URL does not answer

If the server is stopped, still starting, or the URL in AI Settings is wrong, a request routed to Private AI ends with a plain message rather than a connection error — "PIES Private AI is not reachable at the address in AI Settings…" when nothing answers, or "PIES Private AI is not available: the requested model … did not answer…" when a proxy answers but no model is serving. What happens next depends on the policy:

• Air-Gapped, or a pack that keeps data on-prem — the request fails. Nothing goes to the cloud. Start the server (or fix the URL) and try again.
• A policy with a cloud fallback, such as Default Balanced — the fallback model answers, and the audit says so.

Agent runs fail fast with the same message on their run record. On a GPU pod, remember the server stops when you stop the pod: an air-gapped Studio pointed at a stopped pod cannot run any AI until the pod is started again.

11 · Troubleshooting

12 · Frequently asked questions

How long does a first install take?

Mostly the one-time download. On a rented 2× H200 pod, PIES Ultra went from creating the pod to answering in under 30 minutes: about 8 minutes to pull the image, 9 to download the 216 GB of weights, and 8 to load the engine. A restart with the weights already on the volume took about 17 minutes. Downloads on your own network may be slower; plan for the ranges in section 4.

What does it cost to evaluate on a rented GPU?

You pay by the hour while the machine runs, and for the volume while it is stopped. A 2× H200 pod cost about US$9 an hour in our test, so a first install plus an afternoon of evaluation is tens of dollars. PIES Ultra Lite on one H200 cost about US$4.60 an hour. Stop the machine when you are not using it. To stop paying for the volume too, delete it; the next start then downloads the weights again.

Can other applications use PIES Private AI?

Yes, with an inference key (section 5). The API is OpenAI-compatible, with two differences to know about before you connect a third-party client:

• Tool calls come back as text. When the model calls a tool, finish_reason is tool_calls, and the call is a JSON object in the message content: {"name": "…", "parameters": {…}}. The tool_calls field itself is empty. Parse the content.
• Responses are not streamed. A request with "stream": true gets the complete response in one piece.

How many people can use it at once?

The production image batches requests, so several builds and chats run side by side rather than queueing. In our test, four requests sent at once all finished within 7 seconds, faster than running them one after another.

Does stopping the machine lose anything?

No, as long as the volume is kept. The weights and the license live on the volume. On a GPU pod, the admin key is a pod setting, so it survives too.