Troubleshooting
Most install failures are one of these. actana status and actana logs -n 200 are the first two commands.
actana is not found in a new shell
The install links the launcher into ~/.local/bin, which some distributions leave off PATH — and which a shell that started before the install will not have picked up. Add it:
export PATH="$HOME/.local/bin:$PATH"
This is why the installer prints an absolute path rather than a bare actana when ~/.local/bin is not on your PATH. Running the line it printed always works.
macOS: asset…: unbound variable from the one-liner
The stock macOS bash is 3.2, which mis-parses the installer where a variable is followed by a UTF-8 character (say "Downloading $asset…"). The download has not started; nothing is installed. Download the script and run it with a plain locale:
curl -fsSL https://raw.githubusercontent.com/actana/control/main/install.sh -o /tmp/actana-install.sh
LC_ALL=C bash /tmp/actana-install.sh # add flags after, e.g. --version x.y.z-beta
This is a script bug, not something you did. A newer bash (brew install bash) removes the need for the locale override.
The install finished and nothing is running
That is the install working. install.sh places the bundle and stops; actana setup is what makes this machine a Core. Run the line the installer printed. actana status before that says there is no Core installed for this user, which is true until setup has run.
It said it left the launcher alone
Something else already answers to actana — usually npm i -g @actana/cli, whose global shim lands in the same directory. Nothing is broken: it is the same program (one actana), so it runs this Core's status, logs and update as well. The message names where this install's own launcher is, and the actana setup command it prints goes through that launcher. To hand the path over, remove the other install (npm rm -g @actana/cli) and re-run the install.
The service started but nothing is listening
actana logs -n 200
A port already in use and an unreachable --public-host are the two common causes.
The daemon stops when I log out
On macOS this is expected. A LaunchAgent stops at logout and comes back at your next login. Keep the session logged in (System Settings → Users & Groups → Automatic login) if the Core has to stay reachable. See Linux and macOS.
On Linux it means lingering is not enabled — actana status reports this on its Linger row.
loginctl enable-linger "$(whoami)" && actana restart
If your distribution refuses that for a normal user:
sudo loginctl enable-linger "$(whoami)"
The Core is unreachable from the Panel
The Panel dials the Core. Check each layer: is the daemon listening (ss -tlnp | grep 8443 on Linux, lsof -iTCP:8443 -sTCP:LISTEN on macOS), is the service active (actana status), is the firewall open (sudo ufw status, or System Settings → Network → Firewall), and can the Panel machine reach the port (nc -zv <public-host> 8443)?
If the machine's address changed since setup, the certificate no longer covers it. Re-run setup and pair again with a fresh code:
actana setup --public-host <new-address>
actana pair new
getaddrinfo ENOTFOUND host.docker.internal when pairing
A CLI running on the host cannot resolve that name — it exists only inside containers, where Docker Desktop points it at the host. Dial the name that routes from where you are: on the Core's own host with the port published, that is localhost:8443, and localhost must be an entry of ACTANA_PUBLIC_HOST so the certificate covers it. The dial-address table is in Pair from the CLI.
