Skip to main content

Truenas

@thomas/truenasv2026.11.05.3· MIT· 16d agoBEHAVIORS
01README

Administration of a TrueNAS SCALE host (25.04 or 25.10) through its JSON-RPC 2.0 WebSocket API (wss://, API-key auth). Reads apps and their port bindings, NFS/SMB shares and their host allowlists, services, network interfaces, scheduled tasks and each pool's last scrub, and a summary of exposed app ports and shares. Makes a small set of changes: switch an app port between published and exposed, set a custom app's docker networks, create or update an app from Docker Compose YAML with its secrets filled in from a vault, set NFS networks/hosts and SMB hostsallow/hostsdeny, and delete an NFS or SMB share (the data is left alone). Rejects any non-TLS endpoint, because TrueNAS revokes an API key sent in cleartext. Verifies each target first. Does not manage pools, datasets, users, or service start/stop.

02Behaviors1
@thomas/truenasv2026.11.05.3truenas.ts

Global Arguments

ArgumentTypeDescription
endpointstringTrueNAS host or wss:// base URL (required), e.g. nas.example.com or
apiKeystringTrueNAS API key (Credentials → Users → API keys). Supply via vault:
timeoutMs?coerce.numberPer-call timeout in milliseconds (also the job-wait budget)
fn system_info()
Fetch host system info (hostname, version, uptime). Read-only.
fn app_list()
List installed apps with their port bindings (factory: one `app` per app).
fn nfs_share_list()
List NFS exports with their networks/hosts allowlist (factory). Read-only.
fn smb_share_list()
List SMB shares with their hostsallow/hostsdeny (factory). Read-only.
fn service_list()
List system services with state + boot-enable (factory). Read-only.
fn network_info()
Report bindable host IPs (the app port-bind selector contents), interfaces,
fn filesystem_list(path: preprocess, maxEntries?: coerce.number)
List directories on the NAS (`filesystem.listdir`) — entries with type/size
ArgumentTypeDescription
pathpreprocessAbsolute path to list, e.g. /mnt/Backup, or a JSON list of paths to list in
maxEntries?coerce.numberCap on entries recorded (a media dataset can hold thousands); 0 records
fn app_storage(app?: string)
List an app's host-path binds — container mount path ← NAS path, plus where
ArgumentTypeDescription
app?stringApp name (from app_list). Omit to report every app's host-path binds.
fn replication_list()
List replication tasks with their source/target datasets, recursive flag,
fn scheduled_tasks()
List every task the NAS runs on a schedule (scrubs, cron jobs, snapshot tasks,
fn exposure_audit()
Roll up exposure across apps and NFS/SMB shares into one report (published
fn app_set_port_bind(app: string, portKey?: string, portNumber?: coerce.number, bindMode?: enum, hostIps?: array)
Change one app port's bind mode (published↔exposed) and/or host IPs.
ArgumentTypeDescription
appstringApp name (from app_list)
portKey?stringPort config key, e.g. "ldap_port", "admin_port" (preferred; from app_list
portNumber?coerce.numberAlternatively select the port by its current number
bindMode?enumpublished = bound on the host; exposed = container-internal only (closes the
hostIps?arrayHost IPs to publish on (e.g. ["192.0.2.252"]); only meaningful when
fn app_create(name: string, compose: string, secrets?: record, waitMs?: coerce.number)
Create a compose app (one installed from Docker Compose YAML, not the
ArgumentTypeDescription
namestringApp name: lowercase letters, digits and hyphens, at most 40 characters
composestringThe app's Docker Compose YAML. Write each secret as a ${NAME} placeholder
secrets?recordPlaceholder name to secret value, each from a vault:
waitMs?coerce.numberHow long to wait for the create or update job. It pulls the images
fn app_update(name: string, compose: string, secrets?: record, waitMs?: coerce.number)
Replace the compose YAML of a compose app (one installed from YAML,
ArgumentTypeDescription
namestringApp name: lowercase letters, digits and hyphens, at most 40 characters
composestringThe app's Docker Compose YAML. Write each secret as a ${NAME} placeholder
secrets?recordPlaceholder name to secret value, each from a vault:
waitMs?coerce.numberHow long to wait for the create or update job. It pulls the images
fn app_set_networks(app: string, networks: array)
Attach a custom app to a set of docker networks (e.g. join a reverse-proxy
ArgumentTypeDescription
appstringApp name (from app_list)
networksarrayThe complete desired set of docker network names to attach the app to (e.g.
fn nfs_share_set_access(id?: coerce.number, path?: string, networks?: array, hosts?: array)
Set an NFS export's authorized networks/hosts allowlist (the per-client
ArgumentTypeDescription
id?coerce.numberNFS share id (from nfs_share_list)
path?stringAlternatively select the share by export path
networks?arrayAuthorized networks in CIDR, e.g. ["192.0.2.161/32"]. Empty array clears
hosts?arrayAuthorized hosts/IPs. Empty array clears. Omit to leave hosts unchanged.
fn nfs_share_delete(id?: coerce.number, path?: string, confirmPath?: string)
Delete an NFS export rule (e.g. a now-unused share). Verifies the share
ArgumentTypeDescription
id?coerce.numberNFS share id (from nfs_share_list)
path?stringAlternatively select the share by export path
confirmPath?stringSafety guard: when set, must exactly equal the resolved share's export path
fn smb_share_set_access(id?: coerce.number, name?: string, hostsallow?: array, hostsdeny?: array)
Set an SMB share's hostsallow/hostsdeny. Verifies the share first. An empty
ArgumentTypeDescription
id?coerce.numberSMB share id (from smb_share_list)
name?stringAlternatively select the share by name
hostsallow?arrayAllowed hosts/subnets. Empty array clears the allowlist. Omit to leave unchanged.
hostsdeny?arrayDenied hosts/subnets (e.g. ["ALL"] with an allowlist). Omit to leave unchanged.
fn smb_share_delete(id?: coerce.number, name?: string, confirmName?: string)
Delete an SMB share (e.g. a now-unused share). Verifies the share first
ArgumentTypeDescription
id?coerce.numberSMB share id (from smb_share_list)
name?stringAlternatively select the share by name
confirmName?stringSafety guard: when set, must exactly equal the resolved share's name

Resources

system-info(1h)— Host system info (hostname, version, uptime, memory)
app(1h)— An installed app with its published/exposed port bindings
nfs-share(1h)— An NFS export with its networks/hosts allowlist
smb-share(1h)— An SMB share with its hostsallow/hostsdeny
service(1h)— A system service (state + boot-enable)
network-info(1h)— Bindable host IPs + interfaces + GUI bind addresses
dir-listing(1h)— One directory's entries (existence + children)
app-storage(1h)— An app's host-path binds (container path ← NAS path)
replication-task(1h)— A replication task (source/target datasets, schedule, last run)
scheduled-task(1h)— A task the NAS runs on a schedule (scrub, cron, snapshot, SMART, cloud sync, rsync)
pool-scan(1h)— A pool's most recent scrub or resilver, with start and end times
exposure-audit(infinite)— Exposure roll-up across apps and NFS/SMB shares
app-port-result(infinite)— Result of an app_set_port_bind change
app-create-result(infinite)— Result of an app_create
app-update-result(infinite)— Result of an app_update
app-networks-result(infinite)— Result of an app_set_networks change
nfs-share-result(infinite)— Result of an nfs_share_set_access change
smb-share-result(infinite)— Result of an smb_share_set_access change
03Previous Versions4
2026.11.05.2MIT

Modified 1 behaviors

2026.11.05.1MIT(was none)

Modified 1 behaviors

2026.10.11.1

Added 1 behaviors. updated labels

2026.06.24.1
04Stats
A
100 / 100
Downloads
38
Archive size
55.6 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
05Platforms
06Labels