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

  1. 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.
  2. If you want to be sure it's the file we published, compare its SHA-256 with the one on that page.
  3. 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.

Note: Updating? Install the new APK over the old one. Your machines and scripts stay.

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

Debian, Ubuntu, Mint
sudo apt install openssh-server
sudo systemctl enable --now ssh
Fedora
sudo dnf install openssh-server
sudo systemctl enable --now sshd
Arch
sudo pacman -S openssh
sudo systemctl enable --now sshd

Its address on your network:

hostname -I

Check 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 passwordauthentication

macOS

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 en0

Windows

Open Settings → System → Optional features, add OpenSSH Server, then start it. Or, in PowerShell run as administrator:

PowerShell, as administrator
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic

Sign 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

  1. On nukeit's home screen, tap Add machine.
  2. 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.
  3. Pick its platform. It decides how commands and shortcuts are sent.
  4. 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.
  5. Tap Ping to check it's reachable. Ping doesn't sign in, so it works before you enter a login.
  6. 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.

Careful: An SSH port open to the internet is scanned and guessed at constantly, and nukeit doesn't check the machine's host key yet. If you forward a port, use a long password used nowhere else. A VPN avoids both.

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

MachineDoesCommand
LinuxLock your desktoploginctl lock-session $(loginctl show-user $USER -p Display --value)
LinuxShut downsudo -n systemctl poweroff
LinuxRestartsudo -n systemctl reboot
macOSSleeppmset sleepnow
macOSTurn the display offpmset displaysleepnow
macOSShut downsudo -n shutdown -h now
WindowsShut downshutdown /s /t 0
WindowsRestartshutdown /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/nukeit

Add one line naming your user and the full path of each command (command -v systemctl prints it):

Linux
alex ALL=(root) NOPASSWD: /usr/bin/systemctl poweroff, /usr/bin/systemctl reboot
macOS
alex ALL=(root) NOPASSWD: /sbin/shutdown

Then 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.

Debian, Ubuntu
sudo apt install xdotool
echo $XDG_SESSION_TYPE

nukeit 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:$USER

macOS

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

  1. Long-press your home screen, pick Widgets, find nukeit and add it. It's four buttons wide.
  2. In nukeit, open the menu, then Settings → Widget buttons.
  3. 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 saysMeaning
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 runA 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.