# Dead Man's Switch
[](https://opensource.org/license/agpl-v3/)
[](https://crates.io/crates/dead-man-switch)
[](https://docs.rs/dead-man-switch)
This is a simple implementation of a
[Dead Man's Switch](https://en.wikipedia.org/wiki/Dead_man%27s_switch).
Use at your own risk.
Check the f****(as in friendly) code.
Dead man's switches are designed to require positive action
or they will automatically deploy.
They are ideal for situations where you are worried about unforeseen death,
kidnapping, or memory loss.
If you don’t engage the trigger for a certain amount of time,
the switch automatically sends the desired message.
## Features
- **Simple**: Easy to use and setup.
- **Reliable**: Implemented in Rust.
- **Minimal**: Very few dependencies and needs minimal resources.
- **Warning**: Sends a warning email before the final email.
- **Attachments** (Optional): Send attachments with the final email.
- **Tor** (Optional, on by default): Expose the web interface as a Tor onion
service and send the notification emails over Tor, using
[arti](https://gitlab.torproject.org/tpo/core/arti).
## How it Works
> If you want a very simple explanation and the motivation behind the project,
> check my blog post [here](https://storopoli.com/posts/2024-03-23-dead-man-switch.html).
Upon starting the program it will create a [`config.toml`](config.example.toml)
file in an OS-agnostic config file location:
- Linux: `$XDG_CONFIG_HOME`, i.e. `$HOME/.config`, `/home/alice/.config`
- macOS: `$HOME/Library/Application Support`, i.e. `/Users/Alice/Library/Application Support`
- Windows: `{FOLDERID_RoamingAppData}`, i.e. `C:\Users\Alice\AppData\Roaming`
Edit the `config.toml` file to your liking.
Some default values are provided for inspiration.
Dead Man's Switch comprises of two timers:
1. **Warning Timer**: This timer is set to the `timer_warning` (seconds) value
in the `config.toml` file.
If the user do not check-in before timer reaches 0,
it will send a warning email to the users' own specified email address,
the `from` in the `config.toml`.
1. **Dead Man's Timer**: After the warning timer expires, the timer will change
to a Dead Man's timer, and the timer will be set to the `timer_dead_man` (seconds).
If the user do not check-in before timer reaches 0,
it will send the final email to the specified email address in the `config.toml`,
i.e. the `to` in the `config.toml`.
If you want to send attachments with the Dead Man's email,
you can specify the `attachments` option config in the `config.toml`
and provide the _absolute_ path to the file you want to attach.
To check-in, you just need to press the `c` key as in **c**heck-in.
## Installation
There are several ways to install Dead Man's Switch:
1. [Crates.io](https://crates.io/crates/dead-man-switch): `cargo install --locked dead-man-switch-tui`.
1. [GitHub](https://github.com/storopoli/dead-man-switch): `cargo install --git --locked https://github.com/storopoli/dead-man-switch -p dead-man-switch-tui`.
1. From source: Clone the repository and run `cargo install --locked --path .`.
1. Using Nix: `nix run github:storopoli/dead-man-switch`.
1. Using Nix Flakes: add this to your `flake.nix`:
```nix
{
# ...
inputs.dead-man-switch = {
url = "github:storopoli/dead-man-switch";
inputs = {
nixpkgs.follows = "nixpkgs";
flake-parts.follows = "flake-parts";
};
};
outputs = inputs @ { self, ... }:
{
imports = [
{
nixpkgs.overlays = [
# ...
inputs.dead-man-switch.overlays.default
];
}
];
};
}
```
Then `dead-man-switch` will be available as `pkgs.dead-man-switch`;
## Using as a Library
Dead Man's Switch can be used as a library.
This includes all the functions necessary to configure and send emails;
along with the timers.
To do so you can add the following to your `Cargo.toml`:
```toml
[dependencies]
dead-man-switch = "0.10.0"
```
## Web Interface
The Dead Man's Switch is also available as a web interface.
To use the web interface, please follow the instructions below:
1. Change the configuration template file with your own values:
```bash
mkdir my-config-dir
cp config.example.toml my-config-dir/config.toml
```
1. Copy the Docker Compose example file:
```bash
cp docker-compose.example.yml docker-compose.yml
```
1. Run the Docker Compose:
```bash
docker-compose up --detach
```
1. Make sure to [reverse proxy](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/)
the web interface with proper security measures such as HTTPS.
### Tor (arti)
Both the base crate and the web interface can route through the
[Tor](https://www.torproject.org/) network using the pure-Rust
[arti](https://gitlab.torproject.org/tpo/core/arti) implementation — no
external `tor` daemon is required. When enabled:
- **Inbound**: the web interface is exposed as a Tor **onion service**, so it
can be reached anonymously at a stable `<base32>.onion` address without
exposing a clearnet host. The address is available (behind authentication) at
the `GET /api/tor` endpoint and is logged on startup.
- **Outbound**: the warning and dead-man notification emails are delivered to
your SMTP server over Tor.
Tor support is compiled in by default (the `tor` Cargo feature). It is
controlled at runtime by the configuration:
```toml
tor_enabled = true # route the web UI and emails through Tor
tor_nickname = "deadman" # onion service nickname / keystore subdirectory
# tor_state_dir = "/path" # optional; defaults to <config_dir>/deadman/tor
```
arti persists its identity keys under `tor_state_dir`, so the `.onion` address
remains stable across restarts. The first start takes longer while the Tor
client bootstraps; the clearnet listener stays available in the meantime.
A few things to be aware of:
- **Outbound mail uses STARTTLS** on the submission port (e.g. `smtp_port = 587`).
Implicit-TLS (SMTPS, port 465) is not supported (the non-Tor path has the same
requirement).
- **The clearnet listener is not disabled** when Tor is enabled — the web UI is
still served on `0.0.0.0:3000` in addition to the onion service. If you only
want it reachable over Tor, restrict that port at the firewall / container
level.
- **No clearnet fallback for email**: if Tor cannot bootstrap, notification
emails are deferred (not sent over the clearnet) and the failure is logged
repeatedly; `GET /api/tor` reports a `failed` status. This is intentional to
avoid leaking your network location, but it means a permanently-unreachable
Tor network will prevent delivery.
To build without Tor (a smaller binary, e.g. for the TUI), disable the default
feature: `cargo build -p dead-man-switch --no-default-features`.
## License
The source code is licensed under an
[AGPL v3 License](https://opensource.org/license/agpl-v3/)