Multi-host management

The Canasta CLI supports managing Canasta instances on remote hosts from a single controller machine, in addition to managing instances on the local host. This page covers the available targeting mechanisms, saved-host inventory, and prerequisites.

When you need it

Multi-host management is useful when:

• The controller (where you run canasta commands) is separate from the wiki host (where the containers run).
• You manage several Canasta instances spread across multiple machines.
• You want to promote configuration from a development host to staging/production via GitOps.

For a single-machine setup where the controller is also the host, you don't need any of this — the CLI defaults to managing local instances.

Prerequisites

• SSH access from the controller to each remote host. Key-based authentication is recommended; password auth works but you'll be prompted on every command.
• The remote host must satisfy the target-host prerequisites for whichever orchestrator you plan to use (Docker on the host for Compose; kubectl + cluster access for Kubernetes).
• Run canasta doctor --host <remote> to verify before creating instances.

The --host flag

A subset of canasta commands accept a --host flag identifying the target machine:

Command	How --host is used
canasta create --host <host>	Create the new instance on <host>.
canasta list --host <host>	List instances filtered to <host>.
canasta version --host <host>	Filter the list-all view to instances on <host>.
canasta doctor --host <host>	Check dependencies on <host>.
canasta install --host <host>	Install dependencies on <host>.
canasta uninstall --host <host>	Uninstall dependencies from <host>.

For other per-instance commands (canasta start, canasta backup create, canasta gitops pull, etc.), the host is resolved automatically from the instance registry — the host where the instance was created is recorded in conf.json and used for subsequent commands. You don't pass --host on those commands.

The value of --host is either:

• An SSH destination, e.g. user@host.example.com or just host.example.com; or
• A short name from your saved-host inventory (see below).

Inline SSH destination

The simplest form. SSH keys must be in place; new host keys are automatically accepted on first connection.

canasta create --host ubuntu@prod1.example.com -i wiki-prod -w main

Saved hosts (hosts.yml)

For hosts you target repeatedly, save a short name with canasta host add. Saved hosts live in $CANASTA_CONFIG_DIR/hosts.yml on the controller (Linux /etc/canasta/ or ~/.config/canasta/; macOS ~/Library/Application Support/canasta/).

# Save a host
canasta host add --name prod1 --ssh ubuntu@prod1.example.com

# Save a host with a non-default Python interpreter (native mode)
canasta host add --name prod2 --ssh canasta@10.0.0.5 --python /usr/bin/python3

# List saved hosts
canasta host list

# Remove a saved host
canasta host remove --name prod1

After saving, target by short name:

canasta create --host prod1 -i wiki-prod -w main

You can also edit hosts.yml directly for advanced options (SSH port, jump host, custom inventory variables). The file uses standard Ansible inventory format:

all:
  hosts:
    prod1:
      ansible_host: prod1.example.com
      ansible_user: canasta
      ansible_python_interpreter: /usr/bin/python3
      ansible_port: 2222

Listing across hosts

By default, canasta list shows every instance in the registry, regardless of which host it's on. To filter to a single host:

canasta list --host prod1

An instance on a host that can't be reached over SSH is listed as UNREACHABLE, as distinct from NOT FOUND, which means the host answered but the instance directory is gone. canasta list --cleanup removes registry entries for NOT FOUND instances only; add --force to remove unreachable ones too.

The same filter is available on canasta version:

canasta version --host prod1

Inspecting a remote instance

To check pod / PVC / ingress / certificate state for a single instance on a remote host without SSH-ing into it and running orchestrator-native commands:

canasta status --id mywiki

The host comes from the instance's registry entry, so once an instance is registered on a host it doesn't matter which laptop or which controller you run canasta status from — it routes to the right host automatically.

Inspecting a remote Kubernetes cluster

When canasta runs on a different machine than the cluster (the typical multi-host setup), several inspection commands accept --host <name> to dispatch via SSH to a host that has a working kubeconfig — usually the control plane:

# StorageClasses installed on the cluster + canasta's default
canasta storage list --host prod1

# Argo CD admin password (decoded from argocd-initial-admin-secret)
canasta argocd password --host prod1

# Argo CD Applications and their sync/health state
canasta argocd apps --host prod1

# Open Argo CD's web UI via an SSH tunnel + kubectl port-forward
canasta argocd ui --host prod1

These replace the ssh prod1 'sudo k3s kubectl …' reach you'd otherwise need. They work against any registered host that can reach the cluster's API server — typically the control plane node, since canasta install k8s-cp writes a working kubeconfig there.

canasta argocd apps lists Argo CD Applications under Canasta's management — i.e., instances that have been put under gitops with canasta gitops init. A freshly created K8s instance (helm-installed by canasta create, with Argo CD itself running in the cluster) does not yet have an Application; the list is empty until gitops init runs. See Help:Orchestrators for the full picture.

SSH agent forwarding

When the controller manages an instance on another host, every canasta command forwards your local ssh-agent to that host for as long as the command runs. This is what lets commands that run on the host authenticate with your keys, for example git push and git pull in Compose GitOps without --ssh-key, or canasta extension add --repository with a private repository over SSH. Nothing is forwarded when an instance is on the controller itself.

The trade-off is trust in the hosts you manage: while a command runs, anyone with root on that host can use your forwarded agent to authenticate as you wherever your keys are accepted, such as your Git hosting or other servers. Your keys never leave your machine, but they can be used during that window.

• Manage hosts remotely only if you trust every one of them. Otherwise, run canasta on each server itself, so nothing is forwarded.
• To turn forwarding off, set CANASTA_FORWARD_AGENT=no in the environment (also accepted: 0, false, off). Commands that relied on your agent on the host then need their own credentials there: for Compose GitOps, pass --ssh-key or configure a deploy key on the host (see Help:GitOps).
• To notice any use of a forwarded key, load it with ssh-add -c. Your agent then asks for confirmation each time the key is used, so an unexpected prompt shows that something on a host is using it.

# One command without forwarding
CANASTA_FORWARD_AGENT=no canasta gitops pull -i mywiki --ssh-key ~/.ssh/gitops_deploy

# Every command in this shell
export CANASTA_FORWARD_AGENT=no

# Require confirmation for each use of a key
ssh-add -c ~/.ssh/id_ed25519

Promoting configuration across hosts

Multi-host installs are typically paired with GitOps to share configuration across a dev → staging → prod pipeline. Each host joins a shared gitops repository with a different role (source, sink, or both); changes flow from source hosts to sinks via canasta gitops pull. See the GitOps guide for the full workflow.

See also

• Help:Orchestrators — choosing between Compose and Kubernetes orchestrators on a target host
• Help:Backup and restore — Restic-based backup of instances on remote hosts (the same canasta backup commands target hosts via the registry)
• Help:Installation — installing the Canasta CLI on the controller and on each target host
• Help:GitOps — GitOps shared/per-host vars and the source/sink role model
• Help:Multi-node Kubernetes — when "multi-host" also means "multi-node K8s cluster"