Needs the SDK at version 0.9.0 or later: pip install -U "privatemind>=0.9". Workspaces come with an older version, so upgrade there too. The registry is switched on per organisation; see Registry for what it holds, who can see what, and the quota.
Your org's model weights live in the registry as versions. From Python, Client().weights pushes a folder as a version, pulls one back, and manages models. From a shell, the privatemind command pushes, pulls, lists and deletes.
In a workspace or a job the key is already configured. Elsewhere, set PRIVATEMIND_TOKEN to a personal API key. A workspace launched before the registry was released has a key without registry access, and calls raise ForbiddenError with Missing required scope: weights:read. Restarting it keeps that key, so launch a new workspace.
Push
from privatemind import Client
client = Client()
pushed = client.weights.push("./out", "credit-ft", "2026-11-16")
print(pushed.digest, pushed.size_bytes)
print(sum(f.uploaded for f in pushed.files), "of", len(pushed.files), "files sent")Every file under the folder becomes part of the version, except dotfiles, dot folders, .git and __pycache__. Links inside the folder are followed. From 0.10.0, a link that points outside the folder stops the push with ValidationError, unless you pass follow_external_links=True. A file name with a colon, a backslash or a control character, or anything that is not a regular file or folder, stops the push with ValidationError.
Within a model each file is stored once. A file the model already holds at the same path, from an earlier version or a push that stopped halfway, is not sent again. To finish a push that broke off, run the same push again within two days.
| Argument | Default | Notes |
|---|---|---|
folder |
required | The folder to push. |
name |
required | The model: lowercase letters and digits joined by ., _, - or /. |
version |
required | Letters, digits, ., _ and -, up to 128 characters, not starting with . or -. |
exclude |
none | Glob patterns to leave out, matched against each path inside the folder and against the file or folder name. A folder that matches is left out whole. |
allow_pickle |
False |
Push .bin, .pt, .pth, .pkl and .ckpt files. Loading one can run code hidden in it, so without this the push stops and names them. |
follow_external_links |
False |
Push files that links point to outside the folder, for example a Hugging Face cache snapshot whose files link into its blobs folder. Without this the push stops and names the link. |
progress |
none | Called with each WeightsFile once it is sent or found already there. |
It returns a WeightsPush with name, version, digest, size_bytes, image (the pinned name, models/<your-org>/<name>@sha256:…) and files, each a WeightsFile with path, size_bytes, digest and uploaded.
Versions are immutable: pushing one that already exists raises ConflictError before anything is sent. The registry's own refusals, such as a full quota, raise an error that carries the registry's message.
Pull
pulled = client.weights.pull("credit-ft:2026-11-16", "./credit-ft")
print(pulled.path, len(pulled.files))The reference is <name>:<version> or <name>@sha256:<digest>. The pull checks each file against its digest as it arrives, and moves a file into place only once it matches. It writes only regular files and folders inside dest, and refuses a link, an absolute path or a ... progress is called with each file's path and size once it is in place. It returns a WeightsPull with ref, digest, path, size_bytes and files.
List, inspect, share and delete
| Call | What it does |
|---|---|
client.weights.list() |
The models you can read, as a WeightsList with models, your org's registry path, used_bytes and quota_bytes. |
client.weights.get(name) |
One model as a WeightsModel: owner, visibility, description, size_bytes, last_pushed_at, and its versions, newest first. Each WeightsVersion carries version, digest, size_bytes, pushed_at, and used_by, the workspaces, jobs and model servers that use it. Workloads of other members that are private to them are counted in used_by_hidden and not named. |
client.weights.share(name) |
Shares the model with everyone in the org who has compute access. share(name, shared=False) makes it private again, which is refused with ConflictError while another member's workload uses it. |
client.weights.delete(name, version) |
Deletes one version. Leave out version to delete the model and every version. A version in use by any workload, running or stopped, raises ConflictError naming what uses it. |
share and delete need your own API key, as the model's owner or an org admin. A workspace or job key can list, push and pull, and gets ForbiddenError for these two.
Use a version in a job or a model server
import privatemind as pm
job = pm.submit_job(
"python train.py --base /home/privatemind/models/credit-ft",
template="pytorch-gpu",
gpus=1,
weights=["credit-ft:2026-11-16"],
)
server = pm.launch_model_server(
"gpu-cluster",
gpus=1,
weights="credit-ft:2026-11-16",
vllm_version="v0.32.0",
)A job takes a list of up to 8 versions and mounts each read-only under /home/privatemind/models/. Pass {"name": "base", "ref": "credit-ft:2026-11-16"} to choose the folder. A model server takes one version as its model. Both pin the version to its digest: a job when you submit it, a server when you launch it. See Workspace jobs and Model servers.
The command line
The SDK installs a privatemind command for push, pull, list and delete. Sharing is done from Python or the app.
| Command | What it does |
|---|---|
privatemind weights push <folder> <name>:<version> |
Push a folder. Takes --exclude PATTERN, repeatable, --allow-pickle and --follow-external-links. |
privatemind weights pull <name>:<version> <folder> |
Download a version into a folder. |
privatemind weights list |
Your models, with versions, size, sharing, owner and last push, and your org's usage. |
privatemind weights list <name> |
One model's versions, with what uses each. |
privatemind weights delete <name>:<version> |
Delete one version. privatemind weights delete <name> deletes the model and every version. |
The command reads PRIVATEMIND_TOKEN, and PRIVATEMIND_APP_URL when you point it somewhere other than the production platform. It exits non-zero on any error and prints the reason.
HTTP API
The SDK calls the Registry API, which you can call directly from any language.