Using dotMage on your own

dotMage keeps your .env files encrypted on a server you run and syncs them to the machines you use. The server stores only ciphertext; you unlock your copy with a master password that stays on your machine.

Deploy a server

You need a small server — your own machine, a home box, or a cheap VPS. One command installs it via Docker:

$ curl -fsSL https://raw.githubusercontent.com/dotMage/server/main/install.sh | bash

It prints a bootstrap secret (save it — you need it to create the account and add devices) and the server URL. Details and production notes: Deploy server.

1. Authenticate (once per machine)

$ dmage auth --server https://your-server
  # enter your master password — your key is unwrapped locally

2. Put an app under dotMage

From a directory that has a .env:

$ dmage init myapp

3. Day to day

sync decides for you: it pulls when the server is ahead, pushes when you have local changes, and shows a diff when both changed.

$ dmage sync
  # or be explicit:
$ dmage pull myapp
$ dmage push myapp

4. Run without writing secrets to disk

$ dmage exec myapp -- npm run dev

Secrets are passed to the process through its environment; nothing is written to .env.

What else

• Work from another machine. On a machine you're already on, run dmage token (or use the admin panel's Devices → Add a device), then on the new machine run dmage auth --enroll <token>. See Adding another device.
• Store any file, not only .env — see Any file.
• Back up the server database. With end-to-end encryption, a lost database cannot be recovered — see Backup & restore.

Troubleshooting

• “cannot connect to the Docker daemon” — Docker isn't running. Start Docker (or Docker Desktop) and re-run the installer.
• Permission denied on the Docker socket — re-run with sudo, or add yourself to the docker group and log in again.
• Lost the bootstrap secret — read it from the logs: cd dotmage && docker compose logs server | grep "bootstrap secret".
• Can't reach the server from another machine — open the port (default 9470) and use a routable address; for remote use, put it behind TLS or a VPN (TLS / Production).
• “invalid password” on dmage auth — wrong master password. It never leaves your machine and can't be reset on the server; use your recovery code if you set one.
• “key generation changed (AK was rotated)” — the account key was rotated. Run dmage auth again to pick up the new key.
• “… differs from rev N. Overwrite?” on pull — your local file has changes. Keep them (answer no, then dmage push) or discard them (dmage pull --force).

Full reference: Documentation.