Settings
Free & PremiumThe Settings cover everything about the app itself: language, license, updates, keyboard shortcuts, what the sidebar shows, which notifications you get, how your domains can be reached and what WebDonkey sets up on your Mac. Sites, services and configuration files have their own pages.
What you do here
- Check the version, activate a license, pick a language: General.
- Find and install new versions: Updates.
- Bind actions to keys of your own: Keyboard shortcuts.
- Hide pages from the sidebar: Navigation.
- Switch off single kinds of notifications: Notifications.
- Set up the front proxy, HTTPS, the hosts file and the terminal tools: Sites & services.
- Decide where terminals, folders, code and databases open: Open with and the WebDonkey Editor.
- Scheduling without the app, sandbox and system discovery: System.
- Back up the whole setup or move to another Mac: App backup.
- Safety copies of the app database, macOS widgets and uninstalling: More settings.
- Sender of the PDF reports (SEO package): Reports.
Page layout
The page has seven tabs. Below them, the sections of the tab are shown as cards.
| Tab | Sections |
|---|---|
| General | About WebDonkey, License, Language, Appearance, Remote notices, Fetch version status |
| Keyboard shortcuts | Keyboard shortcuts |
| Navigation | Premium features, Sidebar entries |
| Notifications | Which messages you get |
| Sites & services | Default Sites Root, Open code in, Open with, Tools in the terminal, Port forwarding 80 / 443, Sites on the local network, Local SSL root CA, Local CA / SSL, Hosts file |
| Reports | Sender of PDF reports |
| System | Run on schedule without the app, macOS widgets, Sandbox, Backup / Restore, Safety copies of the app database, System discovery, Remove WebDonkey from this Mac |
Most switches take effect at once, there is no save button. Text fields such as the sites folder save as you type. The page remembers the open tab until you quit WebDonkey.
Finding a section
- Settings in the sidebar footer opens the page.
- With ⌘K you find every section in the Settings group, also by keywords such as "sandbox", "hosts" or "language". The palette opens the right tab and scrolls to the section.
- Links from other pages and from this documentation jump straight to a section as well, such as Hosts file.
Free and Premium
Almost everything here is free. Export and import of the app backup are Premium. The Reports tab belongs to the SEO package. You do not pick the theme here but on the Themes page or with the theme switcher.
General Free
The General tab is the first one in the settings. Here you see which version is running, check for updates, activate your license, change the language and decide whether WebDonkey shows notices about remote work and fetches the version status of your software.
Where to find it
Settings in the sidebar footer, General tab. With ⌘K you find the sections About WebDonkey, License, Language, Remote notices and Fetch version status directly.
About WebDonkey
The section shows the logo and the installed version, such as v1.0.50.
- Check for updates checks right away whether there is a newer version. While it checks, it reads Checking…. The result appears below: You are up to date., the number of the available version (the update dialog then opens) or Update check failed: with the reason. More under Updates.
- Open-source licences opens the list of all open-source components inside WebDonkey. The box Search component or licence … filters them, a counter says how many there are (npm and Rust). A click on a component shows its authors, the project's address and the licence text. WebDonkey itself is free to use, but it is not open-source software.
License
Here you activate Premium with the license key from your shop account.
- Copy the key from your shop account.
- Paste it into the field WD1-XXXXX-XXXXX-XXXXX-XXXXX.
- Click Activate.
Above the field the state is shown, such as Free, Premium active or Premium (offline), with the device name and Valid until. With an active license, Included in this licence lists the products and add-on packages of your license with their validity. With an active license you also get Remove license from this device and Manage licenses (opens your account in the shop). After an expired subscription, Check now asks the shop right away.
If you bought an add-on package but have not assigned it to a license yet, it says Package bought but not yet assigned to a licence here. Assign in account takes you to your account. WebDonkey unlocks the package at the next license check, or right away with Check now.
All states, the rules for several devices and the error messages when activating are in Activate a license and Devices and states.
Language
Pick the interface language from the list. There are 16 languages, the choice takes effect at once and is stored. On the first start WebDonkey uses your Mac's language if it is available, English otherwise.
Appearance
This section only points to the Themes page. Open themes takes you there. That is where you pick and build themes; to switch faster, use the theme switcher.
Remote notices
The Remote notices box turns on or off the notice shown on Remote pages and in dialogs that connect to a server or write or delete there. It reminds you that Remote works directly on the server with sensitive data. Default: on. You can also turn it off from the notice itself with Don't show again. The confirmations before deleting and overwriting stay regardless.
Fetch version status
The Fetch version status box decides whether WebDonkey asks endoflife.date, php.net, nodejs.org and nginx.org until when a version is supported and whether vulnerabilities are known. With those answers WebDonkey shows small marks at PHP, Node.js, databases, web servers and CMS, for example when a version has reached its end of support.
- On (default): WebDonkey queries these sites and shows the marks, for example under Services and at the sites.
- Off: no requests go out, and there are no marks.
What happens in the background
- Check for updates asks WebDonkey's update server. It sends the platform, processor architecture, your version and the preferred language of the release notes.
- WebDonkey checks the license with the shop regularly in the background.
- Fetch version status only goes online while the box is on.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Update check failed: with a reason | No connection to the update server | Check the internet connection and try again |
| A message that the key does not look valid | A typo or missing characters | Copy the key from the account again |
| The shop doesn’t know this key. Copy it from your shop account. | The key belongs to no license | Copy it from your shop account |
| A message that activation failed | No connection to the shop | Check the internet connection |
See also
Keyboard shortcuts Free
In the Keyboard shortcuts tab you bind any action from the ⌘K palette to keys of your choice, see all bound shortcuts, turn the undo hint on or off and reset the palette's search statistics. Shortcuts never fire while you type in a field, an editor or the terminal.
Where to find it
- Settings › Keyboard shortcuts
- Manage shortcuts at the bottom right of the palette
- with ⌘K, the action Manage shortcuts or the section Keyboard shortcuts
How to do it
- Under New shortcut, click into the search box and type to find an action. Without input the list shows the entries of the Actions group; with input, up to eight matches from all groups, each with the name of its group.
- Pick the action. It then shows highlighted above the box. Change picks another one.
- Click Record keys and press the keys. They appear next to it as key symbols.
- Click Save.
Without recorded keys, the text next to the button says what works: single letters, combos with ⌘⌥⌃⇧, or sequences like G then S.
Fields and options
| Element | Meaning |
|---|---|
| List of shortcuts | all bound shortcuts with action and keys. No shortcuts yet. if there are none. The bin icon removes a shortcut. |
| New shortcut | search box, Record keys and Save |
| Show the undo banner after a shortcut (⌘Z works either way) | Default: on. Off means no hint after a shortcut; ⌘Z still takes it back for five seconds. |
| Reset search statistics | forgets what the palette learned about your usage (Recent, Popular, order within the groups) |
Rules
- Refused with This combination is taken by the app or the system.: combinations such as ⌘K, ⌘Z, ⌘C, ⌘V, ⌘Q, ⌘W, ⌘, and keys such as Esc, Enter, Tab, Space or the arrow keys on their own. The full list is under Keyboard shortcuts.
- Refused with Already bound to "…".: the shortcut already belongs to another action.
- When firing, the keys of a sequence have to come within one second. Esc as the first key cancels recording.
What happens in the background
WebDonkey stores shortcuts and search statistics in its own database. Both travel with the app backup (category Search & shortcuts).
See also
Notifications Free
In the Notifications tab you decide what WebDonkey tells you about. Notifications land in the bell at the top of the sidebar and, when WebDonkey is not in front, as a macOS banner. Every kind has its own switch, plus a main switch for all of them.
Where to find it
Settings › Notifications, or the section Notifications with ⌘K.
How to do it
- Open the Notifications tab. The section is called Which messages you get.
- Switch off a kind you do not want with its switch.
- The change takes effect at once, there is nothing to save.
Everything on or off
The main switch is at the top. While it is on, it says Notifications are on and Individual kinds can be switched off below. When you turn it off, it says All notifications are off and Nothing is reported. Your selection below is kept. The list below fades but can still be changed. Turn the main switch back on and exactly your previous selection applies.
The kinds
All kinds are on by default.
| Kind | When |
|---|---|
| Package installed | A service such as PHP or MySQL has finished installing. |
| Update available | A new version of WebDonkey or of a package is ready. |
| Backup created | A scheduled backup has run. |
| Scheduled task ran | A scheduled task has finished, successfully or not. |
| Process aborted | A background process crashed or was stopped. |
| AI model ready | A model has finished downloading. |
| ISO downloaded | An ISO image for a virtual machine is ready. |
| Mail in Mailpit | A new mail has arrived in the local mailbox. |
| Monitoring | A monitored site changed state, or a certificate is expiring. |
| Subscription due | A subscription is about to charge, or its cancellation deadline is near. |
| Claude is waiting | Claude Code needs your input or a permission. This needs its Notification hook set up on the Claude page. |
| WebDonkey Editor found | Once, after the editor was installed: terminals, folders, code and databases can now open there, see Open with. |
| Transfer finished | A download or upload in the file manager of an SFTP connection has finished or failed. |
What happens in the background
- WebDonkey checks the switch at the moment a notification is created. A kind that is off is not filed at all, so it shows neither in the bell nor as a macOS banner.
- Notifications already filed stay in the bell until you clear them.
Tips
- Switch off Mail in Mailpit if your project sends a lot of test mail.
- Rather switch off a single kind than all of them. That way you miss nothing important, such as a failed scheduled task.
See also
Sites & services Free
The Sites & services tab controls how your local domains can be reached in the browser, in the terminal and on the network: the front proxy on ports 80 and 443, trust in the local certificate authority, the hosts file and the versions in the terminal. It also holds the folder for new projects, the code editor and Open with, which has a page of its own.
Where to find it
Settings in the sidebar footer, Sites & services tab. With ⌘K you find every section directly, for example "hosts", "port", "lan" or "ca".
Default Sites Root
The folder in which WebDonkey puts new projects. The default is ~/WebDonkey-Sites. Type a path or pick one with Select.
- Fetch locally puts a project you fetch from a server into this folder.
- When a site is deleted, WebDonkey protects this folder: it never goes to the Trash as a project folder itself.
- Sites that already exist stay where they are.
Open code in
The code editor Open in editor uses when the WebDonkey Editor is not installed, or when Open with › Code is set to it. The choices are WebDonkey Editor, Visual Studio Code (default), Cursor, PhpStorm, WebStorm, Zed, Sublime Text, Nova and Default app of the system.
Open with
Decides where terminals, folders, code and databases open. All about it: Open with and the WebDonkey Editor.
Tools in the terminal
The box Use WebDonkey's active versions in the terminal makes your shell use the versions marked active in WebDonkey. It is on from the first start.
- In a new terminal,
php,node,npm,composer,mysql,psql,redis-cliand the command line tools installed through WebDonkey use the version marked active under Services. - Inside a site's project folder and its subfolders, that site's PHP or Node version applies instead, along with WebDonkey's
php.ini. - The same way gives you the
wdcommand line, see CLI (wd).
For this, WebDonkey adds a small directory of placeholders (shims) to your shell PATH, as a marked block at the end of ~/.zshrc. Open a new terminal after switching.
Port forwarding 80 / 443
Starts the front proxy, which binds ports 80 and 443 directly and hands every request to the right site. Your domains then run without a port in the address, so https://myproject.local. It runs under your user account and needs no admin rights.
- The badge shows active or inactive.
- Enable starts the proxy, Disable stops it. Meanwhile it reads Enabling… or Disabling….
- If it cannot start, the error is shown below. Above the page, the banner Front proxy (ports 80/443) failed to start appears as well, with Retry and, where it fits, Free ports 80/443 or Move DDEV router, see Top bar.
Sites on the local network
Normally only you can reach your sites: on this Mac and from Docker containers. Other devices on the Wi-Fi are turned away. The box Share sites on the local network lets them in, for tests with a phone or tablet, for example. Default: off. The change applies to the running front proxy at once.
Turn it on only for tests and off again afterwards. While it is on, any device on the same network can open your sites, including admin areas and test data, in a café or coworking space too.
Local SSL root CA
So https:// addresses of your sites run in the browser without a warning, your Mac has to trust WebDonkey's local certificate authority (CA). A CA issues certificates. WebDonkey has its own, valid only on your Mac.
- The badge shows trusted or not trusted.
- Click Trust CA. macOS asks for a confirmation. No admin password is needed, the CA goes into your user's login keychain.
- During the confirmation it reads Waiting for confirmation….
If the CA is already trusted, the button reads Trust again. You need it when the CA was created anew. You can revoke the trust at any time in the macOS Keychain Access.
Local CA / SSL
Generate local root CA creates the CA in the sandbox if it is missing. Meanwhile it reads Generating…, then CA created in sandbox with the start of the certificate below. Browsers accept the CA only once you trust it in the section above.
Hosts file
The hosts file /etc/hosts tells your Mac which domain belongs to which address. WebDonkey adds the domains of your sites there, so they point to your Mac. Creating or changing a site does this by itself. This section shows whether the file matches your sites and syncs it on request.
- If everything matches, it says All sites are in sync with the hosts file.
- Otherwise the section shows the differences under + add and − remove.
- Apply diff writes the changes. Meanwhile it reads Applying…. If WebDonkey cannot write the file directly, macOS asks for the administrator password.
- If the file is not writable, it says /etc/hosts is not writable. In a terminal: with a command you run yourself.
- Remove all WebDonkey hosts entries takes out every line WebDonkey added. Your own lines stay.
WebDonkey only changes lines that carry its own marker.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| The domain does not open | Hosts entry missing or front proxy off | Check Hosts file and Port forwarding 80 / 443 |
| The browser warns about the certificate | Your Mac does not trust the CA | Trust CA or Trust again |
| The address needs a port | The front proxy is inactive | Enable |
php in the terminal is another version |
The terminal was already open, or the box is off | Open a new terminal, check Tools in the terminal |
| The phone cannot reach the site | Access from the network is off | Turn on Share sites on the local network, and off again after the test |
See also
Open with and the WebDonkey Editor Free
The Open with section in the Sites & services tab decides where WebDonkey hands something over when you click a button to open it: terminals, folders and files, code and databases. It is closely tied to the WebDonkey Editor, the sister app for code, terminal and databases. If the editor is installed, Automatic uses it, otherwise the familiar targets such as Finder or Terminal.
Where to find it
Settings › Sites & services › Open with, or the section Open with with ⌘K.
How to do it
- Open the Open with section.
- Pick a target from the list for each of the four rows. The choice applies at once.
- If a row is set to Automatic, right now: … below it shows what Automatic picks at the moment.
Below the rows it says whether the editor is there: The WebDonkey Editor is installed. or The WebDonkey Editor is not installed. Automatic then uses Finder, the Terminal and WebDonkey’s own DB browser. If the macOS Terminal is open, Terminal is open is shown next to it.
The four settings
| Row | For | Targets |
|---|---|---|
| Terminal | shells for sites, DDEV, Docker and Claude | Automatic, WebDonkey Editor, WebDonkey (built-in terminal), Terminal (macOS) |
| Folders and files | project folders, the sandbox, log files | Automatic, WebDonkey Editor, Code editor (…) with the editor from Open code in, Finder / default app |
| Code ("Open in editor") | the Open in editor button on every site | Automatic, WebDonkey Editor, Code editor (…) |
| Databases | the DB browser button of MySQL, MariaDB and PostgreSQL | Automatic, WebDonkey Editor, WebDonkey (Adminer) |
All four are set to Automatic by default.
What Automatic picks
- Terminal: the macOS Terminal if it is already open. The new window then comes to the front. Otherwise the WebDonkey Editor, and without the editor whatever the button did before (the built-in terminal or the macOS Terminal).
- Folders and files: the WebDonkey Editor, otherwise Finder for folders and the default app for files.
- Code: the WebDonkey Editor, otherwise the app from Open code in (default: Visual Studio Code).
- Databases: with the editor installed, every click asks in the dialog Open database whether Adminer in WebDonkey or the WebDonkey Editor should open. Remember my choice turns the answer into this setting. Without the editor, Adminer opens right away.
Adminer is the database browser that comes with WebDonkey. It opens right on the page, and you type the password into Adminer's login.
What happens in the editor
- A folder or a file opens in the editor.
- A terminal opens as a terminal tab in the editor.
- A database opens in the editor's database window, right at the chosen server.
- Buttons that name Finder explicitly, such as Show in Finder, still open Finder.
When WebDonkey finds the editor for the first time after it was installed, the bell shows WebDonkey Editor found once and points here.
Troubleshooting
If opening fails, WebDonkey briefly shows a message in the window:
| Message | What to do |
|---|---|
| The WebDonkey Editor is not installed. Pick another target under Settings › Open with. | Install the editor or pick another target here |
| The WebDonkey Editor was started but does not answer. | Wait a moment and try again |
| The installed WebDonkey Editor is too old for this. Please update it. | Update the editor, for example under Services |
| … is not installed. Pick another one under Settings › Open code in. | Pick an installed editor under Open code in |
See also
System Free
The System tab covers what runs in the background on your Mac and where WebDonkey keeps its data. From top to bottom it holds Run on schedule without the app, macOS widgets, Sandbox, Backup / Restore, Safety copies of the app database, System discovery and Remove WebDonkey from this Mac. This page explains scheduling, the sandbox and system discovery.
The other sections have pages of their own: App backup for Backup / Restore, More settings for macOS widgets, safety copies and removal.
Where to find it
Settings in the sidebar footer, System tab. With ⌘K you find every section directly, for example "schedule", "sandbox" or "discovery".
Run on schedule without the app
Scheduled tasks and backups normally only run while WebDonkey is open. This section lets macOS run them itself, even while the app is closed and nobody is logged in.
- Click Set up.
- macOS asks for the administrator password once. Confirm.
- Afterwards it says, for example, "5 of 6 run without the app": this many of your schedules are taken over by macOS.
Once set up, there are two buttons:
- Rebuild entries writes all entries with macOS anew.
- Turn off takes the macOS scheduling back. Tasks and backups then only run while the app is open again.
Runs without the app use your user account, and files they create belong to you. Reaching Documents, Desktop, iCloud Drive or external drives needs Full Disk Access for the WebDonkey runner, granted once in the macOS System Settings.
Which schedules stay with the app
Some schedules cannot be run by macOS itself. They stay with the app and are caught up when you next open it:
- a
*in the minute field, Lfor the last day of the month,- more than 96 calendar entries, such as every 10 minutes from 8 to 18 on weekdays.
Every 15 minutes still works, even on weekdays only. If this applies to you, a note appears below the number.
Notes in the section
| Note | What to do |
|---|---|
| The permission is missing | Set up again |
| WebDonkey was updated since this was set up | Set up once more so scheduled runs use the new version |
| A helper with administrator rights from an earlier version is still installed and no longer needed | Remove takes it away, or you set up scheduling again |
Sandbox
The sandbox is WebDonkey's data folder. Outside of it WebDonkey only writes the few marked entries listed under Remove WebDonkey from this Mac. The section shows the path, usually ~/Library/Application Support/WebDonkey, and below it the Size.
- The open button shows the folder in the WebDonkey Editor, in the code editor or in Finder, depending on Open with. It is labelled accordingly: Open in WebDonkey Editor, Open in code editor or Open in Finder.
- Reset sandbox… resets the installed parts, see below.
Resetting the sandbox
- If you also want to delete the data of your local databases, tick Also delete all local databases first.
- Click Reset sandbox…. The button now reads Sure? Click again to confirm, and above it you see what will be deleted.
- Click again within ten seconds. Otherwise the button springs back and nothing happens.
| Without the tick | With Also delete all local databases | |
|---|---|---|
| Installed versions, service configuration, vhosts, site certificates, logs | deleted | deleted |
| Local databases, mail in Mailpit, saved reports | stay | deleted |
| Sites, settings, tasks (the app database) | stay | stay |
| Local CA, key for saved passwords | stay | stay |
| Your project folders | stay | stay |
Before that, WebDonkey stops all services. Afterwards it creates the vhosts and certificates of your sites again. You reinstall the versions your sites need under Services. Make an app backup before a reset if you are unsure.
System discovery
WebDonkey remembers where it found installed tools on your Mac. Rescan discovery clears this cache. Use it when you installed a tool in the terminal (with Homebrew, for example) and WebDonkey should see it right away. Packages, services and database servers then reload.
Tips
- If a backup should run at night, set up scheduling. WebDonkey then does not have to be open.
- If the number at run without the app does not go up, check the schedules for the special cases above.
See also
App backup Premium
The app backup saves your WebDonkey setup as one zip file: sites, services, configurations, certificates and everything the pages keep. You choose what goes in. With the same file you bring back an earlier state or move to another Mac. Export and import are Premium.
Where to find it
Settings › System › Backup / Restore, or the section Backup / Restore with ⌘K.
Exporting
- Click Export backup….
- In the dialog Choose what to export, tick the categories that should go in.
- Click Export backup… in the dialog and choose where to save. The name is
webdonkey-backup-<date>.zip. - Afterwards Backup saved: with the path appears below the buttons.
Cancel closes the dialog without exporting. With no category ticked, the export button stays disabled.
The categories
| Category | Content | Default |
|---|---|---|
| Sites & hosts | your sites and their entries in the hosts file | on |
| Services & settings | installed packages, active versions and app settings | on |
| Databases | database servers, users and bindings, configuration only, not the data | on |
| Server configs | configuration files of web servers and engines | on |
| SSL & certificates | the local CA and issued certificates | off, Sensitive |
| Remote connections | saved SSH/SFTP connections and known hosts | on |
| Remote credentials key | the key that decrypts saved remote passwords | off, Sensitive |
| Scheduled tasks | your cron jobs with their schedule and last run | on |
| API client | collections, requests, environments and the request history | on, Sensitive |
| Monitor | projects and targets, so what is watched, not the check log | on |
| Monitor history | every check result and the Lighthouse reports, grows large | off |
| Subscriptions | what your tools and hosting cost | on |
| Project backups | backup sets with paths, databases, categories and run log. The archives themselves stay where the set points | on |
| Terminal | aliases and SSH hosts of the Terminal page | on |
| AI | specialists, chats and messages, plus Claude's projects to bill. No models | on |
| Toolbox | palettes, icon favourites, snippets, animations, component registries and favourites | on |
| Custom themes | the themes you built or imported | on |
| Search & shortcuts | your keyboard shortcuts and what ⌘K learned about your usage | on |
| Virtual machines | the definitions only, no disk images and ISOs | on |
| Workflows | workflows, the shared variables and what each workflow remembers. Secret variables travel encrypted, the run history stays on this Mac | on |
| Window & layout | dashboard layout, sidebar, navigation preferences and what the tools remember in this window | on |
| Notes vaults | the Markdown notes of all your vaults, without attachments and Obsidian settings | off |
Some categories belong together: Sites & hosts brings Databases along, Remote credentials key brings Remote connections, Monitor history brings Monitor. It works the other way round too: if you untick Databases, for example, Sites & hosts goes as well.
Sensitive categories
Categories marked Sensitive contain secrets. When you tick one, the dialog shows a warning. Keep such a zip private, never in a shared folder:
- SSL & certificates contains the private key of your local CA. Anyone who gets the zip can issue certificates your Mac trusts.
- Remote credentials key, together with the remote connections, makes your server passwords readable. Without it you re-enter the passwords after a restore.
- API client: tokens, passwords and API keys from requests and environments are stored as plain text in the zip. Leave the category out if you pass the zip on.
Importing and moving
- Install WebDonkey on the target Mac and start it once.
- Click Import backup… and choose the zip.
- The dialog Restore from backup shows the categories the file contains, all ticked. Untick what should not come back.
- Decide on Merge instead of replace:
- off (default): the selected categories are replaced entirely by the backup.
- on: existing entries stay, the backup's are added, and on a conflict the backup wins.
- Click Import backup….
- The message Restore complete appears, asking you to restart the app so every page reads the restored state. Restart WebDonkey.
- Install the services you need under Services and put the project folders where the sites expect them.
Backups are portable: on import, WebDonkey rewrites the paths inside configurations for the new Mac.
What is never in the backup
- your project files, meaning the sites themselves
- database contents (MySQL, PostgreSQL, MongoDB) and the root passwords of the local database servers
- installed services and programs, which you reinstall through Services
- disk images and ISOs of virtual machines and the archives of the project backups
- system entries such as the hosts file and the keychain, which the app sets up again
- your license. It stays on the Mac, and an import never changes it. You activate Premium on the new Mac with your key.
For database contents, use the backups on the Databases page or Backups.
Free and Premium
Export backup… and Import backup… are Premium. On Free both buttons are locked, with the Premium badge next to them and Backups (export & import) are a Premium feature.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| This backup contains no restorable data. | The file is empty or not a WebDonkey backup | Pick the right zip |
| Something is missing after the import | The category was not ticked on export, or the app was not restarted | Check the categories and restart WebDonkey |
| Saved server passwords are missing | Remote credentials key was not in the backup | Enter the passwords again |
Separately from the app backup, WebDonkey copies its own database before every version change, see More settings.
See also
Updates Free
WebDonkey looks for new versions by itself and tells you. It never installs on its own: a development environment often has services, SSH sessions or virtual machines running, so you decide when. If the shop announces a change to its terms, WebDonkey asks for your consent before the update.
Where to find it
- The dialog Version … is available appears by itself as soon as there is an update.
- By hand: Settings › General › About WebDonkey, button Check for updates.
- The bell shows Update available, a click leads to the changelog.
How to do it
- When the dialog Version … is available ("An update is ready to install.") appears, read the release notes of the version. If there are none, it says No release notes for this version.
- Click Install and restart.
- The button shows Installing… with the progress in percent.
- WebDonkey then restarts with the new version.
Not now closes the dialog. For this version it only comes back after the next start of WebDonkey, or when you check for updates by hand. Esc or the cross work like Not now.
When the terms change
If the update announces a change to the terms, WebDonkey asks the shop after you click Install and restart whether you still have to agree. A dialog of its own then appears instead of the update dialog:
- The heading names the date from which the new terms apply: Our terms change on ….
- Below it the changes are summarised. Read the new terms opens the full text in the browser.
- Below that it says when your subscription ends if you do not agree, per product if you have several. Until then the current version applies. You get the update either way.
- Choose:
- Agree and update: sends your consent and installs the update.
- Only update: installs the update without consent. WebDonkey asks again with the next update.
- Cancel: back to the update dialog, nothing is installed.
If the consent does not reach the shop, the update dialog says Consent not transmitted, you can agree in your customer account. The update goes ahead anyway.
With a company account, the company agrees in the customer account. The update dialog then only shows the note Your company agrees to the new terms in the customer account. with Open customer account, and the button reads Continue updating.
If the shop does not answer, WebDonkey does not ask and installs right away. The update never depends on this request.
Checking by hand
Under Settings › General, About WebDonkey shows the installed version. Check for updates checks right away, even if you postponed a version with Not now before:
- You are up to date.: nothing to do.
- If there is a new version, its number appears below the button and the update dialog opens. Nothing is installed until you click.
- Update check failed: with the reason, usually the connection to the update server is missing.
What happens in the background
- WebDonkey checks right at start and then every ten minutes while the app runs. If no answer comes, it tries again after a minute, after further failures at growing intervals of up to 30 minutes.
- If you open the changelog and it lists a version newer than yours, WebDonkey checks at once.
- The update server receives the platform, processor architecture, your version and the preferred language of the release notes, nothing about your projects. Details are under Legal.
- Before the first start of a new version, WebDonkey copies its own database. If something goes wrong, you bring the old state back under More settings.
- The Update available notification comes once per version and session, unless you switched that kind off, see Notifications.
Other apps and packages
- You update the WebDonkey Editor and WebDonkey Pages in the app itself or under Services in the group of WebDonkey apps.
- Updates of single packages such as PHP or MySQL run through the Services page, not here.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Update failed: with a reason | The download or the install broke off | Check the internet connection and click Install and restart again |
| Update check failed: | No connection to the update server | Check for updates again later |
| The dialog does not come back | You postponed the version with Not now | Check for updates |
See also
More settings Free
The System tab has three sections you rarely need, but that matter when the time comes: macOS widgets, Safety copies of the app database and Remove WebDonkey from this Mac. The other sections of the tab are explained in System.
Where to find it
Settings › System, or the sections macOS widgets, Safety copies of the app database and Remove WebDonkey from this Mac with ⌘K.
macOS widgets
WebDonkey's widgets for the desktop and the Notification Centre only get data when WebDonkey has Full Disk Access. Without it, macOS would ask on every launch whether WebDonkey may access data from other apps. So WebDonkey leaves the widgets' storage alone then.
| Shown | Meaning |
|---|---|
| Full Disk Access granted, the widgets are getting data | Everything works. |
| Full Disk Access granted, without a note about data | A WebDonkey widget on your desktop gets data within a minute. |
| No Full Disk Access | The widgets get no data. |
Without access, click Open System Settings and switch WebDonkey on there once. macOS never asks again after that. The section notices the change by itself. If you use no widgets, there is nothing to do here. More about the widgets: macOS widgets.
Safety copies of the app database
Before the first start of every new version, WebDonkey copies its own database: sites, connections, backup sets, settings. This is not about the MySQL or PostgreSQL databases of your projects. If something gets lost in an update, you bring the old state back with it.
The list shows every copy with version, kind (before the update or before a restore), time, size and the number of sites. If there is none yet, it says No copy yet. The first one is made before the next version change.
- Show in Finder shows the file in Finder.
- Restore puts the database back to the state of the copy.
Restoring a copy
- Click Restore at the copy.
- The dialog Replace the database with this copy? names the date. Everything added or changed since then is lost: sites, connections, backup sets, settings.
- Before that, WebDonkey keeps a copy of the current state. It will be in the list afterwards. Your project files and your projects' databases are not touched.
- Click Restore and restart. WebDonkey stops the running services and restarts (Restarting…).
After the restart, the top of the section says that the database was restored from a copy. The cross hides the note.
Limits
- WebDonkey keeps the last three copies from before an update and the last three from before a restore. Older ones are removed.
- A copy from a newer version than your app cannot be restored here. It carries the note From a newer version than this app. It cannot be restored here.
- The copies are stored in WebDonkey's data folder. If the whole folder is deleted, by removing WebDonkey with its data or by a clean-up tool, they are gone with it. They protect against lost entries, not against a deleted folder.
Notes in the section
| Note | Meaning |
|---|---|
| The copy before the last version change failed, with time and reason | WebDonkey started anyway. |
| Restoring failed, with time and reason | The database is unchanged. |
| WebDonkey could not restart, so nothing was restored. Please try again. | Click Restore again. |
| This copy is damaged or not a WebDonkey database. | Pick another copy. |
Remove WebDonkey from this Mac
This section takes back everything WebDonkey set up outside its data folder. You see the list first. Afterwards you can drag the app to the Trash without leaving anything behind.
- Click Show what would be removed. The list shows what was found on your Mac, each entry with its path. If nothing is left, it says Nothing of WebDonkey is left outside its data folder.
- Check the list. Entries with a lock need the administrator password.
- Optional: tick Also delete my WebDonkey data (sites, databases, settings). The data is deleted as soon as WebDonkey has quit, and that cannot be undone. Make an app backup first if you want to keep anything.
- Click Remove and confirm in the dialog Remove WebDonkey from this Mac?. macOS asks for the administrator password once.
- WebDonkey then checks that nothing is left: Done. Outside its data folder nothing of WebDonkey is left on this Mac. If something remains, it is listed under Still there:.
- Click Quit WebDonkey and then drag the app to the Trash.
Cancel next to Remove closes the list without removing anything. If you cancel in the password prompt, it says Cancelled in the password dialog. Nothing was changed.
What is removed
| Entry | What it is |
|---|---|
| Sudoers rule | lets WebDonkey run its own helper programs without asking for the password again |
| Helper programs (root) | small programs for steps that need administrator rights |
| Daemon for scheduled tasks | the entries macOS uses to run tasks without the app |
| DNS resolver file | sends the domains of your sites to WebDonkey's name resolution |
| Entries in /etc/hosts | the lines carrying WebDonkey's marker |
| Trusted certificate (login keychain) | the local CA in your keychain |
| PATH entry for shims and wd | the marked block in your shell configuration |
| Claude statusline bridge | WebDonkey's status line and hooks in Claude Code |
| Shell aliases (Terminal page) | the aliases of the Terminal page |
| SSH hosts (Terminal page) | the SSH hosts of the Terminal page in ~/.ssh/config |
| Shell prompt (Terminal page) | the prompt of the Terminal page |
What stays
Your data folder with sites, databases and settings stays unless you explicitly delete the data. Your project folders are never touched. Entries that are not WebDonkey's, such as your own lines in /etc/hosts or a VPN's DNS file, stay unchanged.
If WebDonkey keeps running after the removal, it sets parts of this up again as soon as you change a site. So quit the app right afterwards.