Skip to main content

Running Cwtch on Tails

New Feature

New in Cwtch 1.12

This functionality may be incomplete and/or dangerous if misused. Please help us to review, and test.

The following steps require that Tails has been launched with an Administration Password.

Tails uses Onion Grater to guard access to the control port. We have packaged an oniongrater configuration cwtch-tails.yml and setup script ( with Cwtch on Linux.

The tails-specific part of the script is reproduced below:

Tails needs to be have been setup up with an Administration account

Make Auth Cookie Readable

sudo chmod o+r /var/run/tor/control.authcookie

Copy Onion Grater Config

sudo cp cwtch.yml /etc/onion-grater.d/cwtch.yml

Restart Onion Grater so the Config Takes effect

sudo systemctl restart onion-grater.service

When launching, Cwtch on Tails should be passed the CWTCH_TAILS=true environment variable to automatically configure Cwtch for running in a Tails-like environment:

exec env CWTCH_TAILS=true LD_LIBRARY_PATH=~/.local/lib/cwtch/:~/.local/lib/cwtch/Tor ~/.local/lib/cwtch/cwtch

Install Location

The above command, and the below onion grater configuration assume that Cwtch was installed in ~/.local/lib/cwtch/cwtch - if Cwtch was installed somewhere else (or if you are running directly from the download folder) then you will need to adjust the commands.

Onion Grater Configuration

The oniongrater configuration cwtch-tails.yml is reproduced below. As noted this configuration is can likely be restricted much further.

TODO: This can likely be restricted even further, especially in regards to the ADD_ONION pattern

  • apparmor-profiles:
    • '/home/amnesia/.local/lib/cwtch/cwtch' users:
    • 'amnesia' commands: AUTHCHALLENGE:
      • 'CIRC WARN ERR'
      • '.*' GETCONF:
      • 'DisableNetwork' SETCONF:
      • 'DisableNetwork.*' ADD_ONION:
      • '.*' DEL_ONION:
      • '.+' HSFETCH:
      • '.+' events: CIRC: suppress: true ORCONN: suppress: true INFO: suppress: true NOTICE: suppress: true WARN: suppress: true ERR: suppress: true HS_DESC: response:
    • pattern: '650 HS_DESC CREATED (\S+) (\S+) (\S+) \S+ (.+)' replacement: '650 HS_DESC CREATED redacted '
    • pattern: '650 HS_DESC UPLOAD (\S+) (\S+) .*' replacement: '650 HS_DESC UPLOAD redacted redacted'
    • pattern: '650 HS_DESC UPLOADED (\S+) (\S+) .+' replacement: '650 HS_DESC UPLOADED redacted'
    • pattern: '650 HS_DESC REQUESTED (\S+) NO_AUTH' replacement: '650 HS_DESC REQUESTED NO_AUTH'
    • pattern: '650 HS_DESC REQUESTED (\S+) NO_AUTH \S+ \S+' replacement: '650 HS_DESC REQUESTED NO_AUTH redacted redacted'
    • pattern: '650 HS_DESC RECEIVED (\S+) NO_AUTH \S+ \S+' replacement: '650 HS_DESC RECEIVED NO_AUTH redacted redacted'
    • pattern: '.*' replacement: '' HS_DESC_CONTENT: suppress: true


By default, Cwtch creates $HOME/.cwtch and saves all encrypted profiles and settings files there. In order to save any profiles/conversations in Cwtch on Tails you will have to backup this folder to a non-volatile home.

See the Tails documentation for setting up persistent storage