Get API key

Model weights

View as Markdown

Push, pull, list, share and delete your org's model weights from Python, and all but sharing from the privatemind command.

Note

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

Python
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

Python
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

Python
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.