How to set up nukeit
From installing the APK to running your first script on a machine across the internet. Each part stands on its own; skip to the one you need.
Install the app
- On your phone, open the download page, enter your invite code and complete the check. The APK downloads. No code yet? Ask me for one.
- If you want to be sure it's the file we published, compare its SHA-256 with the one on that page.
- Open the APK. Android asks once to allow installs from your browser or file manager; allow it, then install.
nukeit needs Android 7.0 or later. It asks for nothing but internet access and network state.
Turn on SSH on your machine
nukeit signs in to your machines over SSH with a username and password, so each one needs an SSH server that accepts passwords. Note the machine's address while you're there.
Linux
sudo apt install openssh-server
sudo systemctl enable --now sshsudo dnf install openssh-server
sudo systemctl enable --now sshdsudo pacman -S openssh
sudo systemctl enable --now sshdIts address on your network:
hostname -ICheck that password login is allowed. If this prints passwordauthentication no, set PasswordAuthentication yes in /etc/ssh/sshd_config or the file under /etc/ssh/sshd_config.d/ that says no, then restart SSH.
sudo sshd -T | grep -i passwordauthenticationmacOS
Open System Settings → General → Sharing and turn on Remote Login. Under its info button, allow your user. The Mac's Wi-Fi address:
ipconfig getifaddr en0Windows
Open Settings → System → Optional features, add OpenSSH Server, then start it. Or, in PowerShell run as administrator:
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType AutomaticSign in with your Windows account name and its password. If you sign in to Windows with a Microsoft account, that's the Microsoft account's password, not your PIN. The address is the IPv4 Address that ipconfig prints.
Add the machine
- On nukeit's home screen, tap Add machine.
- Give it a name, then its IP or hostname: an IPv4 or IPv6 address, or a name. The SSH port is 22 unless you changed it.
- Pick its platform. It decides how commands and shortcuts are sent.
- Pick its network: LAN when the phone and the machine share a network, Internet for anything else, VPNs included. Internet skips the ICMP ping and allows more time for a slow link.
- Tap Ping to check it's reachable. Ping doesn't sign in, so it works before you enter a login.
- Enter the username and password, and Save machine. Open it and tap Connect to check the login.
Reach it from anywhere
Away from home, the phone needs a way in. There are two.
A VPN (recommended)
Install Tailscale, or a VPN like it, on the machine and on the phone, and sign both in to the same account. In nukeit, use the machine's Tailscale address (it starts with 100.) or its Tailscale name, and set the network to Internet. Nothing on the machine is opened to the internet.
A forwarded port
In your router, forward an outside port, say 2222, to the machine's port 22. In nukeit, use your public IP address, or a dynamic DNS name if it changes, with port 2222 and network Internet.
Write scripts
A script is a name and a command, saved per machine. On Linux and macOS nukeit runs it as sh -lc '…': a login shell, so your PATH and profile are loaded, and quotes in your command are taken care of. On Windows the command runs as you typed it, in OpenSSH's shell, which is cmd unless you changed it. For PowerShell, write powershell -NoProfile -Command "…".
The app waits up to two minutes for a command and shows its exit code: 0 means it worked. Anything longer should start in the background and finish on its own:
nohup ~/backup.sh > /tmp/backup.log 2>&1 &To make a script need a slide, open it with the pencil and switch on Dangerous. Its Execute button becomes Slide to run, and on the widget it asks for a second tap.
Examples
| Machine | Does | Command |
|---|---|---|
| Linux | Lock your desktop | loginctl lock-session $(loginctl show-user $USER -p Display --value) |
| Linux | Shut down | sudo -n systemctl poweroff |
| Linux | Restart | sudo -n systemctl reboot |
| macOS | Sleep | pmset sleepnow |
| macOS | Turn the display off | pmset displaysleepnow |
| macOS | Shut down | sudo -n shutdown -h now |
| Windows | Shut down | shutdown /s /t 0 |
| Windows | Restart | shutdown /r /t 0 |
The commands with sudo -nneed a sudo rule (Root commands). An SSH session can't lock a Windows desktop by itself; use the Win+L shortcut instead.
Run root commands without a password
nukeit can't answer a password prompt, and a password typed into a script ends up in its command, the terminal and the widget. Allow the exact commands without one instead. On Linux or macOS, create a rule:
sudo visudo -f /etc/sudoers.d/nukeitAdd one line naming your user and the full path of each command (command -v systemctl prints it):
alex ALL=(root) NOPASSWD: /usr/bin/systemctl poweroff, /usr/bin/systemctl rebootalex ALL=(root) NOPASSWD: /sbin/shutdownThen write the script with sudo -n, as in sudo -n systemctl poweroff. The -n makes sudo fail at once instead of waiting for a password nobody will type.
Send keyboard shortcuts
Open a machine, go to Keys and tap + to pick from presets for its platform, or type your own, like Ctrl+Alt+T. Sendpresses it on the machine's desktop, so someone has to be signed in there.
Linux
nukeit presses keys with xdotool, which needs an X11 desktop. Install it, then check the session type in a terminal on that desktop: x11 works, waylandcan't receive simulated keys.
sudo apt install xdotool
echo $XDG_SESSION_TYPEnukeit sends keys to display :0. If shortcuts fail even on X11, run this in a terminal on the desktop to let your own user reach the display:
xhost +SI:localuser:$USERmacOS
Keys are pressed through System Events, which macOS lets only allowed apps do. If shortcuts don't arrive, open System Settings → Privacy & Security → Accessibility, press + and add /usr/libexec/sshd-keygen-wrapper, the program behind Remote Login.
Windows
An SSH session can't reach the desktop, so nukeit presses the keys through a one-off scheduled task in your signed-in session. The account nukeit signs in as has to be the one signed in at the desktop. Win+L locks it.
Use the widget
- Long-press your home screen, pick Widgets, find nukeit and add it. It's four buttons wide.
- In nukeit, open the menu, then Settings → Widget buttons.
- Tap Assign on a colour, choose a machine, then a script.
A press runs the script in the background, without opening the app. The widget gives a machine 15 seconds to answer and a command 30. After a run, the button shows how it went for three seconds:
| The button says | Meaning |
|---|---|
| Running… | The machine is being reached, or the command is running. |
| Done ✓ | The command finished with exit code 0. |
| Exit 1 (or another number) | The command ran and reported a failure. |
| Failed ✗ | nukeit couldn't sign in, or the command ran past 30 seconds. |
| Tap again to run | A dangerous script waiting for its second tap. Without one, it goes back after four seconds. |
Each button keeps its own copy of its machine's address and login and its script's command. nukeit updates it whenever you change one, and clears a button whose script you delete.
Troubleshooting
What nukeit says, and what to do about it.
- Can't find <host>. Check the address.
- The name doesn't resolve from where the phone is. Check the spelling, or use the IP address. A name that only works at home, or only on your VPN, fails everywhere else.
- Nothing answered on port <port> at <host>: SSH isn't running there, or a firewall refuses it.
- The machine is there but nothing listens on that port. Turn SSH on (Turn on SSH), check the port number, and check the machine's firewall.
- No route to <host> from this network.
- The phone isn't on a network that leads there, typically a LAN address used from mobile data. Use a VPN or a forwarded port (From anywhere).
- No answer from <host>:<port> in time. The machine may be off, or the port isn't forwarded.
- The machine may be asleep or off, the router may not forward the port, or the connection is too slow. Setting the machine's network to Internet allows more time.
- The machine refused the login. Check the username and password.
- Use the account's short name, not its display name. On Windows with a Microsoft account, use that account's password, not your PIN. On Linux, check password login is allowed (Turn on SSH).
- No result after 120 s. The command may still be running on the machine; its output won't show here.
- The command outlived the app's two minutes. Start long jobs in the background (Scripts).
- sudo: a password is required
- The command needs root and there's no sudo rule for it yet (Root commands).
- xdotool isn't installed on this machine.
- Install it: sudo apt install xdotool on Debian and Ubuntu, sudo dnf install xdotool on Fedora.
- This machine's desktop runs Wayland, which can't receive xdotool shortcuts.
- Sign in to an X11 session (on Ubuntu, Ubuntu on Xorg from the login screen's gear), or use a script instead: loginctl lock-session $(loginctl show-user $USER -p Display --value) locks the screen on either.
- Failed ✗ on the widget
- Run the same script from the app: it shows the full error.
Keep it safe
nukeit keeps your machines, scripts and passwords in its private storage on the phone, and the widget keeps a copy of the four buttons' logins. They aren't encrypted yet. Nothing leaves the phone except your SSH connections.
- Keep a screen lock on the phone.
- Give nukeit an account of its own on each machine, with sudo rules for exactly what it runs.
- Keep passwords out of commands; use a sudo rule instead (Root commands).
- Reach machines through a VPN rather than a forwarded port.
- Mark anything destructive as dangerous, so it needs a slide, or a second tap on the widget.