Available Tools | PodWarden Hub

This page is the reference for the tools PodWarden offers, grouped into sections below. How many are callable depends on your instance's tier settings: the tools your PodWarden instance offers. To see the exact list, connect a PodWarden Core to your account, or ask your AI client to run list_tool_categories. A connected model is announced only the facade's own tools — find_tools, describe_tools, list_tool_categories, load_skill, and the execute_read / execute_mutate / execute_destroy doors — and discovers and calls everything else through them, so the full catalog never bloats the model's context. Tools are classified as read-only, mutating (create/update/deploy), or destructive (delete). The instance-wide tier switch (Settings → MCP) controls which of those tiers are exposed, and is the only setting that restricts what a connected model may call — a token's role does not. See What gates a tool call.

Removed and merged tools: Earlier versions of PodWarden carried alias and duplicate tools. They were removed in favour of the canonical tools below, and an agent that calls an old name is told the replacement. The old workload aliases (list_workload_definitions, get_workload_assignment, and the rest) are now list_stacks, get_deployment, and so on; list_system_apps / get_system_app became list_components / get_component; get_settings became get_system_config; the *_hub_ddns_* tools became list_hub_parent_domains, allocate_hub_domain, list_domains with sync_hub_domains, and delete_domain; list_cloudflare_dns_records became import_cloudflare_domain followed by list_domain_records. Three pairs were merged: cancel_host_provisioning into cancel_provisioning_job, set_domain_ddns into update_domain, and mark_all_system_messages_read into mark_system_message_read (omit message_id to mark all).

Infrastructure overview

Tool	Type	Description
`get_infrastructure_overview`	Read	High-level summary: cluster count, host count, GPU totals, workload status, recent deployments
`find_gpu_capacity`	Read	Find available GPU capacity across all hosts and clusters, grouped by GPU model
`check_cluster_capacity`	Read	Check available CPU and memory capacity across clusters, compare against deployed workloads
`troubleshoot_workload`	Read	Diagnose issues: fetches deployment, stack, cluster status, pod events, and logs

Clusters

Tool	Type	Description
`list_clusters`	Read	List all Kubernetes clusters with node counts, network types, and live status
`get_cluster`	Read	Detailed cluster info including nodes, managers, and live Kubernetes status
`get_cluster_extended`	Read	Extended live info: K8s version, namespaces, node details with CPU/memory/GPU, running pods
`get_cluster_storage_classes`	Read	List StorageClasses available in a cluster
`get_cluster_affected`	Read	Get resources that would be affected by deleting a cluster (hosts, deployments, endpoints)
`get_network_health`	Read	Check network health of a cluster
`list_node_taints`	Read	List all taints on a Kubernetes node
`create_cluster`	Mutating	Create a new cluster — provide kubeconfig directly or fetch via SSH from a control-plane node
`update_cluster`	Mutating	Update cluster settings: name, kubeconfig, namespace, SSH fetch host, protection
`cordon_node`	Mutating	Mark a node as unschedulable
`drain_node`	Mutating	Drain a node — evict all pods so it can be taken offline for maintenance
`taint_node`	Mutating	Add a taint to a Kubernetes node (taints repel pods that don't tolerate them)
`uncordon_node`	Mutating	Mark a node as schedulable again (undo cordon)
`untaint_node`	Mutating	Remove a taint from a Kubernetes node by key
`delete_cluster`	Destructive	Delete a cluster record from PodWarden (does NOT uninstall K8s from hosts)
`delete_cluster_node`	Destructive	Remove a stale node from a Kubernetes cluster (deletes the K8s node object)
`delete_namespace`	Destructive	Delete an empty PodWarden-managed `pw-*` namespace (e.g. one an undeploy left behind)

Components

Platform-level components (operators and add-ons) installed on a cluster, such as Longhorn or the backup operator. list_components / get_component replace the old list_system_apps / get_system_app.

Tool	Type	Description
`get_component`	Read	Get the full detail of one component on a cluster, as JSON
`list_components`	Read	List the components of a cluster with their versions
`disable_component`	Mutating	Set a component's desired-state to disabled (declarative; no run_remove)
`enable_component`	Mutating	Set a component's desired-state to enabled (declarative; no run_ensure)
`install_component`	Mutating	Install a component and set its desired-state to enabled
`restart_component`	Mutating	Restart (reconcile-now) a component — generation bump, NOT a rollout
`upgrade_component`	Mutating	Upgrade a component to a target version (version-targeted reapply)
`uninstall_component`	Destructive	Uninstall a component and set its desired-state to disabled

See the System Apps guide for installation and detection details.

Hosts

Tool	Type	Description
`list_hosts`	Read	List all managed hosts with hardware info, status, GPU details, cluster membership
`get_host`	Read	Full host details including hardware specs, GPU info, cluster assignment
`update_host`	Mutating	Update host metadata: display name, notes, network types
`probe_host`	Mutating	SSH into a host to gather hardware info (CPU, RAM, disk, GPU) and detect Kubernetes
`set_gateway_role`	Mutating	Enable or disable the gateway role on a host (ingress entry point)
`detect_host_public_ip`	Mutating	Detect the public IP of a host via SSH (for DNS validation)
`add_host`	Mutating	Add a host manually by IP or hostname
`provision_host`	Mutating	Install K3s agent and join the host to a cluster (runs in background)
`wipe_host`	Destructive	Remove K3s from a host and reset to discovered state (runs in background)
`register_cluster_from_host`	Mutating	Register an existing K3s/K8s installation on a host as a PodWarden cluster
`provision_as_control_plane`	Mutating	Install K3s server on a host and create a new cluster (runs in background)
`detach_host_from_cluster`	Mutating	Remove a worker node from its cluster (K8s + PodWarden DB)
`probe_host_network`	Mutating	Probe a host's network topology via SSH
`reconfigure_host_networking`	Mutating	Non-destructive k3s networking reconfiguration
`reset_host_status`	Mutating	Reset a stuck host from 'provisioning' or 'error' back to 'discovered'
`delete_host`	Destructive	Delete a manually-added host from PodWarden

Stacks

Templates that define what to deploy (image, resources, GPU requirements).

Tool	Type	Description
`list_stacks`	Read	List all stacks with resource summaries
`get_stack`	Read	Full stack details including env schema, volume mounts, registry credentials
`create_stack`	Mutating	Create a new stack (container template)
`update_stack`	Mutating	Update an existing stack — only provided fields are changed
`delete_stack`	Destructive	Permanently delete a stack

Deployments

Bindings of stacks to clusters — the actual deployments.

Tool	Type	Description
`list_deployments`	Read	List deployments with status, cluster, stack, and deploy info
`get_deployment`	Read	Full deployment details including env values, resolved volumes, deployment log
`get_workload_logs`	Read	Get container logs and pod status from a deployed workload
`check_network_compatibility`	Read	Pre-flight check: verify workload network requirements match cluster capabilities
`create_deployment`	Mutating	Bind a stack to a cluster (starts in "pending" status)
`update_deployment`	Mutating	Update deployment config — changes take effect on next deploy
`deploy_workload`	Mutating	Deploy a deployment to its target Kubernetes cluster (runs in background)
`undeploy_workload`	Destructive	Remove a workload from Kubernetes — deletes Deployment and non-retained PVCs
`update_config_template`	Mutating	Update a single config template in a deployment without resending all config_values
`run_in_pod`	Mutating	Execute a command inside a running pod belonging to a managed deployment
`proxy_to_service`	Mutating	Send an HTTP request to a deployment's ClusterIP service via in-cluster proxy
`migrate_workload`	Mutating	Migrate a deployed workload to a different node (pre-flight PV affinity checks)
`restart_deployment`	Mutating	Restart a deployment by triggering a Kubernetes rollout restart
`delete_deployment`	Destructive	Delete a deployment record (does NOT undeploy — undeploy first)

Apps

Tool	Type	Description
`list_apps`	Read	List apps with their stacks, deployments, and current status
`get_app`	Read	Full app details including stack config, deployment status, and history

Ingress rules

Tool	Type	Description
`list_ingress_rules`	Read	List all ingress rules with domain, backend, gateway, and status
`get_ingress_rule`	Read	Full ingress rule details including DNS check results and proxy status
`create_ingress_rule`	Mutating	Create a new ingress rule — supports managed (K8s) and manual (IP:port) backends
`update_ingress_rule`	Mutating	Update an existing ingress rule — only provided fields are changed
`check_ingress_dns`	Mutating	Check DNS resolution — resolves domain A record and compares to gateway IP
`check_ingress_http`	Mutating	HTTP health check — verifies the full chain: DNS → gateway → ingress → backend
`check_ingress_tls`	Mutating	Check TLS certificate validity: issuer, expiration date, days remaining
`apply_ingress_rule`	Mutating	Generate and deploy proxy config for a single ingress rule
`apply_all_ingress_rules`	Mutating	Regenerate and deploy the full proxy config for a gateway host
`delete_ingress_rule`	Destructive	Permanently delete an ingress rule and remove its proxy config

DDNS

Tool	Type	Description
`list_ddns_configs`	Read	List all DDNS configurations with provider, status, current IP, and last update
`get_ddns_config`	Read	Full DDNS config details (sensitive fields like API tokens are masked)
`get_ddns_status`	Read	Current public IP and status summary of all DDNS configurations
`create_ddns_config`	Mutating	Create a new DDNS config (Cloudflare, DuckDNS, Webhook, or Hub provider)
`update_ddns_config`	Mutating	Update a DDNS config — use "***" for token fields to preserve existing values
`test_ddns_config`	Mutating	Force a DNS record update to verify credentials and provider connectivity
`delete_ddns_config`	Destructive	Delete a DDNS config (DNS records are NOT removed — clean up at provider)

Hub catalog

Browse and import stack templates from PodWarden Hub.

Tool	Type	Description
`test_hub_connection`	Read	Test connectivity to the configured PodWarden Hub
`list_hub_categories`	Read	List template categories (e.g. "AI & Machine Learning", "Databases")
`list_hub_templates`	Read	Browse templates with search and category filtering
`get_hub_template`	Read	Full template details: image, resources, env schema, ports, volumes
`check_hub_updates`	Read	Check for updates on Hub-imported stacks
`import_hub_template`	Mutating	Import a Hub template as a local stack

Domains

The domain registry, Cloudflare DNS records, and domains allocated through PodWarden Hub. These replace the old *_hub_ddns_* tools.

Tool	Type	Description
`list_domain_records`	Read	List DNS records from Cloudflare for a domain
`list_domains`	Read	List all registered domains with type, DNS status, and ingress rule counts
`list_hub_parent_domains`	Read	List the parent zones PodWarden Hub offers for allocating a Hub domain
`allocate_hub_domain`	Mutating	Allocate a subdomain on PodWarden Hub and register it as a domain (e.g. `myapp.podwarden.com`)
`check_domain_dns`	Mutating	Check DNS resolution for a domain and compare with gateway IP
`create_domain`	Mutating	Register a domain in the domain registry
`create_domain_record`	Mutating	Create a DNS record in Cloudflare for a domain
`import_cloudflare_domain`	Mutating	Import a domain from a Cloudflare DDNS configuration, then use `list_domain_records` to see its DNS records (replaces `list_cloudflare_dns_records`)
`publish_domain`	Mutating	Publish the current gateway public IP to this domain's DNS provider now
`sync_hub_domains`	Mutating	Reconcile the local domain registry with the subdomains allocated on PodWarden Hub (use with `list_domains`)
`update_domain`	Mutating	Update a domain: notes, `ddns_mode`, and the gateway it is bound to (`gateway_host_id`, or `clear_gateway` to unbind). Replaces `set_domain_ddns`
`update_domain_record`	Mutating	Update a DNS record in Cloudflare
`delete_domain`	Destructive	Permanently delete a domain from the registry (for a Hub domain this releases the subdomain)
`delete_domain_record`	Destructive	Delete a DNS record from Cloudflare

Storage

Tool	Type	Description
`list_storage_connections`	Read	List all storage connections (NFS/S3 backends) with config and status
`get_storage_connection`	Read	Storage connection details including connectivity test results
`test_storage_connection`	Mutating	Test connectivity — NFS: TCP/RPC/export/mount+speed test; S3: endpoint/upload/download speed
`create_storage_connection`	Mutating	Create a new storage connection (NFS or S3)
`update_storage_connection`	Mutating	Update an existing storage connection — only provided fields are changed
`create_nfs_storage_class`	Mutating	Deploy NFS provisioner to a cluster and create a StorageClass from an NFS storage connection
`delete_storage_connection`	Destructive	Delete a storage connection (workloads using it will lose access)

Backups

Restic-based backup policies for deployed workloads.

Tool	Type	Description
`get_backup_policy`	Read	Get details of a backup policy including recent snapshots
`list_backup_policies`	Read	List backup policies
`list_backup_snapshots`	Read	List Restic snapshots for a backup policy
`create_backup_policy`	Mutating	Create a backup policy for a deployed workload
`restore_backup_snapshot`	Destructive	Restore a workload from a Restic backup snapshot
`resume_backup_policy`	Mutating	Resume a suspended backup policy's CronJob
`run_backup_now`	Mutating	Trigger an immediate backup for a policy (creates a one-off K8s Job)
`suspend_backup_policy`	Mutating	Suspend a backup policy's CronJob (prevent new scheduled backups)
`update_backup_policy`	Mutating	Update a backup policy
`delete_backup_policy`	Destructive	Delete a backup policy and its K8s CronJob

Network zones

Group nodes by network reachability.

Tool	Type	Description
`get_zone`	Read	Get full details of a network zone including member hosts
`list_zones`	Read	List all network zones with host counts and subnet configuration
`create_zone`	Mutating	Create a network zone for grouping nodes by network reachability
`update_zone`	Mutating	Update a network zone's properties
`delete_zone`	Destructive	Delete a network zone

Registry connections

Encrypted pull credentials for private container registries.

Tool	Type	Description
`list_registry_connections`	Read	List private container-registry connections — passwords are never returned
`create_registry_connection`	Mutating	Create a registry connection: encrypted pull credentials a stack or deployment names in `registry_credentials`
`test_registry_connection`	Mutating	Test a registry connection: reachability and credential authentication
`update_registry_connection`	Mutating	Update a registry connection
`delete_registry_connection`	Destructive	Permanently delete a registry connection

Volume migrations

Move a stack's volume data to a different PVC.

Tool	Type	Description
`get_volume_migration`	Read	Get status and progress for a single volume migration job
`list_volume_migrations`	Read	List all volume migration jobs for a stack (workload definition)
`cancel_volume_migration`	Mutating	Cancel a pending or running volume migration job
`retry_volume_migration`	Mutating	Retry a failed or cancelled volume migration job
`start_volume_migration`	Mutating	Start a new volume migration job — tars source data over SSH into a PVC

Workload updates

Available updates for deployed workloads.

Tool	Type	Description
`list_workload_updates`	Read	List available workload updates from the local cache
`apply_workload_update`	Mutating	Apply an available update to a workload (async — returns immediately)
`dismiss_workload_update`	Mutating	Dismiss the current available update for a workload

Longhorn

Longhorn distributed storage on a cluster.

Tool	Type	Description
`get_longhorn_nodes`	Read	Get Longhorn storage nodes for a cluster
`get_longhorn_settings`	Read	Get global Longhorn storage settings for a cluster
`get_longhorn_volumes`	Read	Get Longhorn volumes for a cluster
`install_longhorn`	Mutating	Install Longhorn distributed storage on an existing K3s cluster
`update_longhorn_node_scheduling`	Mutating	Enable or disable scheduling on a Longhorn storage node
`update_longhorn_settings`	Mutating	Update global Longhorn storage settings on a cluster

Node access

Time-limited, human-approved SSH access to managed nodes. See Node SSH access.

Tool	Type	Description
`request_node_access`	Mutating	Request time-limited SSH access to a node — returns an approval URL a human must open
`revoke_node_access`	Mutating	Revoke an SSH access grant, immediately terminating access
`run_node_command`	Mutating	Execute a command on a node via an approved SSH access grant

System messages

Health check alerts and infrastructure issues.

Tool	Type	Description
`get_system_messages_summary`	Read	Get a quick summary of unread system messages by severity
`list_system_messages`	Read	List system messages (health check alerts and infrastructure issues)
`mark_system_message_read`	Mutating	Mark one system message as read, or every active one when `message_id` is omitted (replaces `mark_all_system_messages_read`)
`run_health_check`	Mutating	Trigger an immediate health check run
`delete_system_message`	Destructive	Delete a system message permanently

Appliance

Tool	Type	Description
`get_deploy_status`	Read	Get the honest deploy status from the appliance launcher

Discovery and execution

The facade tools a connected model sees first. Everything else is found with find_tools and run through the three execute_* doors, one per tier.

Tool	Type	Description
`describe_tools`	Read	Get the full description and JSON argument schema for named tools
`execute_read`	Read	Run a read-only PodWarden tool found via find_tools
`find_tools`	Read	Search PodWarden's tools and skills, and return what matches
`list_tool_categories`	Read	List the categories of tools PodWarden offers, with how many are in each
`load_skill`	Read	Fetch a skill procedure by name, with its declared tier and version range
`execute_mutate`	Mutating	Run a PodWarden tool that creates or changes infrastructure
`execute_destroy`	Destructive	Run a PodWarden tool that permanently deletes something

Provisioning jobs

Tool	Type	Description
`list_provisioning_jobs`	Read	List provisioning jobs with status, host, playbook, and timing
`get_provisioning_job`	Read	Full job details including stdout and stderr output
`cancel_provisioning_job`	Mutating	Request cancellation of a running provisioning job — by `job_id` (preferred) or by `host_id` (replaces `cancel_host_provisioning`)
`cleanup_provisioning_jobs`	Destructive	Delete all completed provisioning jobs (non-running/pending)

Users

Tool	Type	Description
`list_users`	Read	List system users with role, status, and last active time
`get_user`	Read	Full user details
`create_user`	Mutating	Create a new system user with email and role
`update_user`	Mutating	Update a user's name, email, role, or status
`set_user_password`	Mutating	Set or change a user's local password (8-72 characters)
`delete_user`	Destructive	Remove a system user

Secrets

Tool	Type	Description
`list_secrets`	Read	List all secret keys — values are NOT returned, only key names and metadata
`list_ssh_key_pairs`	Read	List SSH key pair names (each pair is `{name}_ssh_private` + `{name}_ssh_public`)
`get_secret_address`	Read	Compute where a workload secret is stored: its Config v2 scope and store key
`get_secret_usage`	Read	Show every deployment's variables and which tier and stored secret wins for each
`list_stack_secrets`	Read	List all env vars for a stack: declared secrets and plain compose env vars
`get_secret`	Mutating	Get a decrypted secret value by key (handle with care)
`set_secret`	Mutating	Create or update a secret — value is encrypted at rest (AES-256-GCM)
`generate_ssh_key_pair`	Mutating	Generate a new SSH key pair and store both halves in secrets
`add_stack_secret`	Mutating	Add a new secret to a stack: stores it where the stack is deployed
`copy_secrets`	Mutating	Copy workload secrets to other addresses server-side; values never leave the store
`generate_secrets`	Mutating	Replace workload secrets with fresh random values generated server-side (rotation)
`get_deployment_variables`	Mutating	List every variable a deployment's containers receive and where each one resolves
`promote_env_value`	Mutating	Encrypt a deployment's inline (plaintext) env value into the secret store
`delete_secret`	Destructive	Delete a secret by key — cannot delete SSH keys in use by provisioned hosts
`delete_secrets`	Destructive	Delete several stored workload secrets at once
`move_secrets`	Destructive	Move or rename workload secrets server-side: copy, then delete the source
`remove_stack_secret`	Destructive	Remove a secret declaration from a stack schema and delete its stored value

Settings

Tool	Type	Description
`update_settings`	Mutating	Update registry default settings

System configuration

Tool	Type	Description
`get_system_config`	Read	Get system configuration (including the registry defaults) and the running Core version (env vars override DB values; replaces `get_settings`)
`update_system_config`	Mutating	Update system config — only pass sections to change (SMTP, OIDC, Hub)
`test_smtp`	Mutating	Send a test email using the configured SMTP settings
`test_oidc`	Mutating	Test OIDC discovery — validates issuer URL, fetches provider metadata

What gates a tool call

There is no per-token permission model. Earlier versions of this page described a viewer / operator / admin matrix in which mutating and destructive tools returned 403 Forbidden to a lower-privileged token. No such gate exists. PodWarden Core's authorization model is flat: every authenticated caller has the same access, secret values included. The role stored on an MCP token (admin or readonly) is displayed in the UI but is read by no authorization check.

Selecting a role does not limit a token. If you need to limit what an AI assistant can do, the control is the instance-wide tier switch below — or the decision not to mint the token at all.

Three things actually decide whether a tool call succeeds. None of them is the token's role.

1. Authentication

The request must carry a valid Bearer pwm_… token that is still active and unexpired. Anything else is rejected before tool gating runs. An MCP path whose identity cannot be resolved fails closed and exposes nothing.

2. The instance-wide tier switch

Set in Settings → MCP. This is the only gate that works at tool granularity:

Tier	Covers	Default
`read`	Read tools — `list_`, `get_`, logs, capacity and health checks	Enabled
`mutate`	Create / update / deploy tools — and `get_secret`, deliberately classified as mutating so a read-only instance cannot disclose secret values	Disabled
`destroy`	Delete / release tools	Disabled

It is an operator switch for the whole deployment, not a per-principal permission: it applies identically to every caller, and a token whose stored role reads admin is capped by it exactly like any other. If the setting cannot be read, it fails safe to read-only.

Because the tier filter runs before the facade is announced, a Core with mutate and destroy off does not announce the execute_mutate and execute_destroy doors at all — the connected model is offered only the read door.

A tool outside an enabled tier returns an MCP error frame rather than an HTTP status, carrying a stable reason code:

Reason	Meaning
`tier_disabled`	The tool exists, but its tier is switched off for this instance
`unknown_tool`	No tool by that name is registered

3. Credential-class rules

These key on how you authenticated, not on what role you hold — so they are not a role system returning by another name, and they apply to every MCP token equally. An MCP token is a machine credential, and machine credentials are refused (403 Forbidden) on the surfaces that administer other credentials:

Surface	Effect on an MCP token
`create_user`, `update_user`, `set_user_password`, `delete_user`	Refused. Reading users (`list_users`, `get_user`) is unaffected
Creating or modifying MCP tokens	Refused — a token cannot mint itself a more capable successor
The `terminal` and `runtime` sections of `update_system_config`	Refused. The other sections are unaffected
Environment inventory	Refused
Approving or extending a node-access grant	Refused — approval requires an interactive human

One genuine per-token setting exists: node_ssh_access, disabled by default, which grants a root shell on managed nodes. An operator turns it on for an individual token, and it is re-validated live against the database on every use. See Node SSH access.

Scope an MCP token by whether you mint it, not by how you configure it. Within the enabled tiers, any valid token can read every secret the instance holds and change everything it manages. This posture is only appropriate while everyone who can authenticate to the instance is trusted with full administrative access to it; it is not a model for a deployment with users of differing trust.