pytruenas

A typed, Pythonic client and CLI for the TrueNAS middleware API.

pytruenas speaks the middleware's JSON-RPC 2.0 websocket protocol directly — over wss:///ws:// to a remote host, or over the local unix socket (ws+unix://) when running on the NAS itself. It exposes the whole API surface through an attribute-style namespace, adds convenience helpers for the common create/update/upsert patterns, a remote-filesystem abstraction, an optional typings generator, and a small CLI for scripting host configuration.

Running commands and reading files is delegated to hostctl: a client is a hostctl host, so run() and path() pick whichever transport a target actually offers rather than assuming one.

Install

pip install pytruenas

Optional extras:

Quickstart

from pytruenas import TrueNASClient

# Remote host (api key, or "user:password", or a token)
client = TrueNASClient("nas.example.com", "1-<64-char-api-key>", sslverify=False)

# Attribute-style access to any API namespace/method:
for user in client.api.user.query():
    print(user["username"])

# Convenience helpers for common DB patterns:
client.api.user._upsert(("username",), username="svc", full_name="Service", group_create=True)

# Running on the NAS itself talks to the local unix socket, no auth:
local = TrueNASClient()            # ws+unix:///var/run/middleware/middlewared.sock
print(local.api.system.info())

Commands and files

run() and path() are inherited from hostctl, which selects a transport rather than assuming one:

client = TrueNASClient("nas.example.com", api_key, shell="ssh://root@nas.example.com")

client.run("zpool status", capture_output="stdout", encoding="utf-8").stdout
client.path("/mnt/tank/notes.txt").read_text()

client.capabilities      # {"run", "path", ...} -- what this target can actually do
client.last_selection    # which transport served the last run(), and why

webshell runs commands over /websocket/shell — the same PTY the web UI's Shell page uses — so a host reachable on the API port but not on 22 (NAT, a firewall allowing only 443) can still run commands. Name providers explicitly with executor= / path= to force or exclude one.

Output is exact: commands and input travel base64-encoded and output is framed by markers the command prints, so the terminal's echo, prompt and banner never reach your result. Uncaptured stdout streams live; stderr is captured separately (delivered when the command ends); input=/stdin= are delivered through a temporary file, never typed into the terminal.

Credentials

TrueNASClient(target, credentials) accepts, for the second argument:

• an API key string "<id>-<64 chars>",
• "user:password" (optionally "user:password\n<otp>"),
• a token string,
• a (user, password) tuple,
• None / omitted → local socket auth.

Credentials.from_env() reads TN_CREDS. Credentials may also travel in the target (wss://root:secret@nas). In a URI an OTP follows the password after a newline as a keyed line — otp:<token>, with the newline percent-encoded: wss://root:secret%0Aotp:123456@nas. In the plain credential string above the token follows the newline on its own ("user:password\n123456").

A password containing /, ? or # must be percent-encoded (%2F, %3F, %23); a raw one is refused, because the URL parser would otherwise read the rest of it as a host, port and path.

CLI

pytruenas --help
pytruenas query user -f username=root nas.example.com
pytruenas call system.info nas.example.com          # any method by dotted name
pytruenas dump-api nas.example.com > api.json
pytruenas generate-typings --path typings --api-version v26.0.0 nas.example.com
pytruenas deploy nas.example.com                    # install pytruenas ON the host

The target host(s) are the trailing positional arguments — a command's own positionals (like query's namespace) come first, then the hosts. Each target may be comma-separated and supports [A-Z]/[0-9] range expansion (e.g. 'nas[1-3].example.com'); with no target the command runs against localhost. --parallel N runs several targets concurrently. Filter query with -f/--filter KEY=VALUE (repeatable).

Running on the appliance

TrueNAS has a read-only root and no pip, so deploy bootstraps instead: it asks the target which distributions it already has, bundles only the difference, and copies that over. In practice that is five pure-Python packages under a megabyte — the appliance already ships requests, websocket-client, pyyaml, asyncssh and jinja2.

pytruenas deploy nas.example.com                 # a single executable .pyz
pytruenas deploy --mode dir nas.example.com      # an unpacked bin/ + lib/ tree
pytruenas deploy nas.example.com -- call system.info   # install, then run there

Everything after -- runs on the target once it is installed. The default destination is under /var/db/system, which is a dataset on a data pool and so survives an update — unlike /var/db itself, /root or /data, which live in the boot environment and are replaced by one. A digest is recorded beside the payload, so redeploying verifies instead of re-copying; --force overrides. An existing --path that a previous deploy did not create is refused rather than replaced.

When pytruenas is a dependency of your own tool rather than the thing being deployed, name yours as the root: --pkg-root mytool (or PYTRUENAS_PKG_ROOT), and your package ships with pytruenas bundled underneath it.

--source repo ships a working tree as-is instead of an installed dependency closure — the files a clone would have, filtered by whichever of .gitignore, .ignore and .bundleignore are present, with nothing needing to be installed locally first (needs pytruenas[repo]). It requires --mode dir: a zipapp needs an importable package root, which a working tree does not have.

pytruenas deploy --source repo --mode dir --repo-root . nas.example.com

Typings generator

generate-typings turns a host's API definition into a package of .pyi stubs so editors and type checkers understand client.api.<namespace>.<method>(...). It is validated against the full real API (every version in a live dump).

pytruenas generate-typings --path truenasapi_typings/current nas.example.com

Development

py -3.14 -m venv .venv/3.14-nt-amd64
.venv/3.14-nt-amd64/Scripts/python -m pip install -e ".[dev,ssh,config,codegen]"
.venv/3.14-nt-amd64/Scripts/python -m pytest

Supports Python 3.9+. The run() tests need a POSIX shell and skip on Windows, so verify anything touching command or path dispatch on a real target.

License

MIT — see LICENSE.