WebDonkey
Free & PremiumThe WebDonkey window (⌘4) shows WebDonkey next to your code: your sites, the services, their configuration files, logs, scheduled tasks and workflows. You start and stop sites and services, open configs and logs as tabs and run tasks, all without leaving the editor. While WebDonkey runs, everything is live. When it doesn't, the window shows the sites from WebDonkey's database.
What you do here
- See sites, open them in the browser, start and stop them, open one as a project: Sites.
- Start, stop and restart services and edit their configuration: Services.
- Pick the PHP and Node version for a project's terminals: PHP and Node version.
- Open logs of services, sites, custom logs and logs on servers as tabs: Logs.
- Run scheduled tasks and workflows right away: Scheduled tasks and workflows.
- See the state of your project's site at the bottom in the status bar: Status bar.
- Move between the editor and WebDonkey: Open in WebDonkey.
Layout of the window
| Area | What is there |
|---|---|
| Header | A dot and "WebDonkey 1.x is running" with the arrow Show in WebDonkey, or "WebDonkey is not running" with Start WebDonkey. |
| Front proxy notice | "Front proxy is stopped" with Start, when WebDonkey's front proxy is not running. |
| Sites | All sites, the project's site highlighted. Unfolded. |
| Services | The services and below them the Shims block. Only while WebDonkey runs. |
| Configuration | The configuration files of the services and of the site. Folded. |
| Logs | Custom logs, logs of services and sites, with Premium the logs on servers. Folded, only when there are logs. |
| Scheduled tasks | Cron jobs on the Mac, with Premium on servers too. Folded, only while WebDonkey runs and there are any. |
| Workflows | Your workflows from WebDonkey (marked as Beta there). Folded, only while WebDonkey runs and there are any. |
Click a section heading to fold or unfold it, the editor remembers that. The number next to the heading is the number of entries. The editor asks WebDonkey for its state every 3 seconds. If WebDonkey reports an error, it shows at the bottom of the window.
Without WebDonkey
The window needs WebDonkey on this Mac. If WebDonkey is not installed, it says: "This needs WebDonkey on this Mac (sites and local services). Remote, databases, themes and notes work without it with your Premium key." If WebDonkey is older than the editor needs, the window asks you to update WebDonkey. You get WebDonkey at shop.webdonkey.io.
Free and Premium
The window is free, and so are sites, services, shims and local scheduled tasks. Premium covers: logs as tabs in the editor, logs and scheduled tasks on servers, the global php.ini and Follow log in the status bar. On Free, logs and Follow log open WebDonkey's Logs page, logs and tasks on servers do not show up, and the global php.ini stays locked. Prices are on webdonkey.io/pricing.
If you don't need the window, hide it under Settings › Features › Tool windows.
Sites Free
The Sites section lists every site from WebDonkey. The site your open project belongs to is highlighted. From here you open a site in the browser, start or stop it and make its folder the project in the editor.
Where to find it
WebDonkey window (⌘4), Sites section. The number next to the heading is the number of your sites. When there are none, it says "No sites yet". You create new sites in WebDonkey.
What a row shows
- a dot: green when the site is running, grey when it is off, pulsing while it starts or stops,
- the domain, a lock for SSL and the PHP version ("PHP 8.3"),
- in the tooltip the site's project folder.
Hover over a row and three buttons appear:
| Button | What it does |
|---|---|
| Open in browser | Opens the site in the browser, with https:// for SSL. Only for a running site with WebDonkey running. |
| Open as project | Makes the site's project folder the project in the editor. If the site has no project folder of its own, it is its web root (DocRoot). |
| Start / Stop | Turns the site on or off. Only while WebDonkey runs. |
Open a site as a project
- Hover over the row and click Open as project (folder icon).
- If a project is open already, the editor asks where to: New window (the default), This window (replaces the open project, unsaved files are asked about first), Attach (as another folder in the same window) or Cancel.
- If the folder is already open in another window, the editor brings that window to the front.
Which site belongs to the project
A site belongs to the open project when the project folder is its project folder, lies inside it or contains it. If several match, the one with the longest path wins. That site is highlighted, its services show in the status bar, and its configuration is at the top of the Configuration section (see Services).
When WebDonkey is not running
The window then reads the sites from WebDonkey's database. Open as project still works, Open in browser, Start and Stop are greyed out. Start WebDonkey with Start WebDonkey at the top of the window.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| The site does not open in the browser | The site or the front proxy is stopped | Start the site; at "Front proxy is stopped" click Start. |
| No site is highlighted | The project lies outside every site | Open the site with Open as project. |
| The buttons are grey | WebDonkey is not running | Start WebDonkey. |
See also
Services Free & Premium
The Services section shows WebDonkey's services, that is web servers, PHP-FPM, databases, Node, Mailpit and everything else WebDonkey runs for your sites, plus sites' own processes. You start, stop and restart them. In the Configuration section you open their configuration files as tabs, and when you save, WebDonkey checks them before anything is reloaded.
Where to find it
WebDonkey window (⌘4), sections Services and Configuration. Services only shows while WebDonkey runs.
Start and stop services
Each row shows a dot (green = running, grey = stopped, yellow pulsing = starting or stopping, red = error), the name and the version. A site's own process (an npm start, say) reads "domain · process". Running services are at the top, stopped ones are collected under "n stopped". Click it to show them.
- Hover over a service.
- A running service offers Restart and Stop, a stopped one Start.
- Click it. The dot pulses until WebDonkey is done.
Below the services sits the Shims block for the PHP and Node version in your terminals, see PHP and Node version.
Configuration
The Configuration section lists the files that configure services. A click opens the file as a tab in the editor.
| Group | Contents |
|---|---|
| This project · domain | Only when the project belongs to a site: the PHP files of its PHP version (for example "PHP 8.3 → php.ini"), the web server's file for this site (for example "nginx → … .conf"), plus .user.ini in the site's web root and, with Apache, .htaccess. |
| PHP (all versions) | The global php.ini that applies to every PHP version. Premium. |
| per service and version | The service's files, for example of PHP 8.4 or nginx. |
If .user.ini or .htaccess is missing, create shows next to it. A click creates the file and opens it. For .user.ini the editor says: "For PHP values of this site only. PHP-FPM reads the file by itself, within five minutes." Greyed-out files do not exist yet: WebDonkey creates them when the service starts for the first time. The editor reads the list again when WebDonkey starts or stops.
The section is there even when WebDonkey is not running, as long as there are files.
Checking on save
A configuration file carries the label Service config on its tab, a file with a site's own values Site override (it takes effect without a reload). When you save a service config with ⌘S, this happens:
- WebDonkey checks the file, for nginx, Apache, Caddy and PHP: "…: checking the configuration …".
- If it has an error, the editor reports "…: the configuration has an error. Nothing was reloaded." The errors are marked in the file. If the error is in another file, the notice names file and line.
- If everything is fine, it asks "The configuration is fine. Reload …?" with Reload and Later. If there is no check for the file, it asks "Reload …? There is no check for this file."
- After Reload it reports what was reloaded. If the service is not running, it reads the file at its next start.
If WebDonkey is not running, the editor only saves: "WebDonkey is not running: saved, but not checked and not reloaded." Auto-save does not trigger a check. You turn the check off under Settings › Services › Check service configs on save.
Free and Premium
Starting and stopping services, opening, editing and checking files are free. The global php.ini (PHP (all versions)) is edited with Premium. On Free it carries a lock, and a click says "The global php.ini is edited with Premium, as in WebDonkey."
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| The Services section is missing | WebDonkey is not running | Start WebDonkey at the top of the window. |
| A dot stays red | The service ended with an error | Look at its log, see Logs. |
| Nothing happens after saving | Auto-save, or the check is turned off | Save with ⌘S, check the setting. |
| A file is greyed out | The service never ran | Start the service once. |
See also
PHP and Node version Free
In the editor's terminals, php, node, composer and co. use the version that applies in the current folder. WebDonkey's shims take care of that: small launchers that sit in front of your own PATH and pick the right version on every call. In a site's folder the site's version applies, even while WebDonkey is not running. In other projects WebDonkey's global version applies, or you set a version of your own for the project in the editor.
Where to find it
- In the terminal: a badge like "PHP 8.3 · Node 22 · shop.test" shows what applies in the current folder. In the Terminal window it sits on the right of the tab strip, for terminals in the editor area at the top right as soon as you hover over them. The tooltip says "In the terminal: … Click to change the version."
- In the WebDonkey window (⌘4): under Services, while WebDonkey runs, the Shims block with the switch In editor terminals and one row each for PHP and Node with version and origin. Clicking a row opens the same menu as the badge.
- Settings › Services › Terminal: WebDonkey shims in editor terminals and PHP, Node and site badge in the terminal.
The origin shows next to the version:
| Origin | Meaning |
|---|---|
| from … (the site's name) | The site sets the version. |
| this project | You picked a version of your own for this project in the editor. |
| WebDonkey's default | WebDonkey's global version applies. |
Change a site's version
- Open a project that belongs to a site and click the badge in the terminal, or PHP or Node under Shims.
- The menu shows "PHP of …" and "Node of …" with the installed versions. The current one is checked.
- Pick a version. WebDonkey switches the site, exactly as in WebDonkey itself. The editor reports "… now uses PHP 8.4. New commands in the terminal follow right away."
If WebDonkey is not running, the top of the menu says "WebDonkey is not running: your choice is noted". Your choice then waits in the editor and goes to WebDonkey as soon as it answers again: "… noted: will be applied the next time WebDonkey starts." The menu shows the noted version with that hint. Picking the site's current version again drops the noted choice.
A version for a project without a site
- Open a project that belongs to no site and click the badge or the row under Shims.
- The menu says "Applies to new terminals and runs of this project in the editor" and shows PHP for this project and Node for this project: at the top WebDonkey's default (…), below the installed versions.
- Pick a version. "PHP 8.4 now applies to new terminals of this project." With WebDonkey's default the global version applies again.
The choice applies to terminals and launcher runs of this project you open afterwards. Running terminals keep their version. With no project open at all, the menu only shows "Global version (no WebDonkey project)".
Settings
| Setting | Meaning | Default |
|---|---|---|
| WebDonkey shims in editor terminals (also In editor terminals under Shims) | php, node, composer and co. use the site's version in the project folder. Applies to new terminals, your shell profile stays unchanged. | on |
| PHP, Node and site badge in the terminal | Shows the badge above the terminal. | on |
What happens in the background
- For zsh and bash the editor puts WebDonkey's shim folder at the start of
PATH, after your own startup files (.zshrc,.bash_profileand so on) have run. It does not change your files. Other shells start without this step. - The shims resolve the version anew on every call. Switch the site and the very next
phpcommand in an open terminal uses the new version. - A site's version belongs to WebDonkey and lives in its database. A project's own version is kept by the editor in its app data folder and handed to new terminals of that project.
- If WebDonkey's
wdcommand exists, the editor setsEDITORandVISUALin its terminals towd edit --wait. That waygit commitorcrontab -eopen a tab in the editor.
Free and Premium
Shims, badge and version choice are free. They need WebDonkey on this Mac.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| No badge in the terminal | WebDonkey is not installed, the badge is turned off, or the terminal runs on a server | Check the setting. |
php uses the wrong version |
The terminal was opened before the shims were switched, or the shell is neither zsh nor bash | Open a new terminal. |
| The chosen version does not arrive | WebDonkey is not running, the choice is noted | Start WebDonkey. |
| The menu is nearly empty | No other versions are installed | Install versions in WebDonkey. |
See also
Logs Free & Premium
The Logs section of the WebDonkey window lists the logs WebDonkey knows: your own log files, the logs of services and sites and, with Premium, the logs on your servers. A click opens the log as a tab next to your code, without switching to WebDonkey.
Where to find it
WebDonkey window (⌘4), Logs section. It starts folded and only shows when there are logs. The logs are grouped, with headings as soon as there is more than one group:
| Group | Contents |
|---|---|
| Custom logs | Log files you added yourself in WebDonkey. |
| Services | The logs of the running services, nginx or PHP-FPM for example. |
| Sites | The logs of the sites, of their own processes for example. |
| Remote logs | Logs on your servers, with the server's name next to them. Premium. |
Logs of services and sites show while WebDonkey runs. Custom logs and remote logs come from WebDonkey's list and are there even when WebDonkey is not running. A row's tooltip shows the path, for remote logs with the server.
Open a log
- Unfold Logs.
- Click a log (or select it with the keyboard and press ↩ or Space). It opens in the shared log tab.
- Click another log afterwards and it replaces that tab, as long as the tab is still open. That way log tabs don't pile up.
- For two logs side by side, click Open in its own tab (plus icon at the end of the row) on the second one. A tab opened like that is never replaced.
A local log opens as a normal file tab. You work in it like in any file, with search for example.
Logs on servers
A remote log opens as a tab of its own with the notice for working on servers. At the top you see name, server, path, size and when it was last read ("read …"). If the server rotated the file, a label says it started over.
| Button | What it does |
|---|---|
| Refresh | Reads the log again now. |
| Live | "Re-read this log every few seconds while it is on screen": every 5 seconds while the tab is visible. Click again to turn it off. |
Without Live, the tab reads at the interval you set for this log in WebDonkey, while the log is active there, at most every 5 seconds. On first open it shows what WebDonkey has read already and only reads when there is nothing yet. With no lines yet it says "(no entries yet)". You set up remote logs in WebDonkey, see Remote logs in WebDonkey.
What happens in the background
- The editor reads local logs directly as files.
- It reads remote logs with WebDonkey's commands over SSH on your server, only on a click, with Live or at the set interval, and only while the tab is visible.
- The lists of custom logs and remote logs are fetched from WebDonkey every 15 seconds.
Free and Premium
Logs as tabs in the editor are part of Premium. On Free an arrow sits at the end of the row, and a click opens WebDonkey's Logs page. If WebDonkey is not running, shop.webdonkey.io opens instead. Remote logs do not show up at all without Premium. A remote log tab without Premium says "Remote logs are Premium".
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| The Logs section is missing | There are no logs, or WebDonkey is not running and you have no custom logs | Start WebDonkey. |
| "This log is no longer set up in WebDonkey." | The remote log was removed in WebDonkey | Close the tab or set the log up again in WebDonkey. |
| A red message in the remote log | The connection to the server failed | Check the connection in WebDonkey. |
| A click opens WebDonkey instead of a tab | Free | Activate Premium or read the log in WebDonkey. |
See also
Scheduled tasks and workflows Free & Premium
The WebDonkey window lists the scheduled tasks WebDonkey runs on your Mac (cron jobs), with Premium also the tasks on your servers, and your workflows. When you need a run right now, an import or a cache warm-up for example, you start it here with one click. You create and edit tasks and workflows in WebDonkey.
Where to find it
WebDonkey window (⌘4), sections Scheduled tasks and Workflows. Both start folded and only show while WebDonkey runs and there are entries.
Scheduled tasks
When there are local and server tasks, they sit under the headings Local and Remote. Each row shows:
- a dot: green = active, grey = off, yellow pulsing = running right now, for local tasks red = the last run ended with an error,
- the name and the schedule as a cron expression, for example
*/5 * * * *, - for server tasks the name of the connection,
- in the tooltip the command, for server tasks with the connection in front.
To run a task right away:
- Unfold Scheduled tasks.
- Hover over the task.
- Click Run now (play icon).
WebDonkey runs the task, for server tasks on the server. What came of it, you see in WebDonkey with the task. A local task above the Free limit cannot be started, its button is grey.
Workflows (Beta)
WebDonkey marks workflows as Beta. Each row shows a dot (yellow pulsing = running, red = last run failed, green = on and ready, grey = otherwise), the name and the description in the tooltip. At the end of the row is one of two buttons:
| Button | When | What it does |
|---|---|---|
| Run now (play icon) | The workflow needs no input and has been on or run before | Starts it right away. The editor reports "Workflow “…” started". |
| Start in WebDonkey (arrow) | The workflow asks for input when it starts, or it was imported and never turned on or run | Opens WebDonkey's Workflows page. There you enter the input or look over the imported workflow once. |
The button is greyed out when the workflow has no trigger or is locked, for example because it is above the Free limit or uses building blocks that need Premium.
What happens in the background
The editor asks WebDonkey over its local control connection to run the task or workflow. It runs nothing and schedules nothing itself. It fetches the lists from WebDonkey every 3 seconds.
Free and Premium
Local tasks and workflows are free, within the limits WebDonkey sets for Free. Tasks on servers are part of Premium, on Free they do not show up. Prices are on webdonkey.io/pricing.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| The sections are missing | WebDonkey is not running, or there are no entries | Start WebDonkey, create tasks in WebDonkey. |
| A red dot | The last run failed | Look at the run in WebDonkey. |
| Run now is grey | The task or workflow is locked | Check in WebDonkey why. |
| Server tasks are missing | Free | Activate Premium. |
See also
Status bar Free
At the bottom left of the status bar the editor shows what WebDonkey is doing for your project: whether WebDonkey runs, which site the project belongs to and whether its services are running. The dots let you start a stopped service without opening a window.
The entries
| Entry | What it shows | A click |
|---|---|---|
| WebDonkey and site | A dot (green = WebDonkey running), the site's domain and its PHP version. Without a site it reads "WebDonkey" or "WebDonkey not running". While WebDonkey runs, the number of running services follows ("· 9 services"). | Opens the WebDonkey window. |
| Open in browser | Only with WebDonkey running and a site. | Opens the site in the browser. |
| The site's services | One dot per service the site needs: green = running, red = stopped or error, yellow pulsing = starting. | Opens the services menu. |
| Update … | Shows up when a new version of the editor is ready. | Opens Updates. |
The WebDonkey and site entry only shows when WebDonkey is installed on this Mac. The service dots only show while WebDonkey runs and the project belongs to a site.
Which services a site needs
- If the site has a process of its own (an
npm start, say), it is just that one: "domain (own process)". - Otherwise: PHP-FPM in the site's PHP version, its web server (nginx, Apache or Caddy) and every installed database (MySQL, MariaDB, PostgreSQL), because a site does not record which one it uses.
- If WebDonkey's front proxy is stopped, it comes first as a red Proxy dot.
Start or stop a service, or follow its log
- Click the dots. The menu "Services of …" lists each service with its state (running, stopped, starting …, error).
- Hover over a service. The submenu offers Start, Stop, Restart and Follow log.
- Follow log opens a terminal tab "Log …" running
tail -n 200 -Fon the service's log. The last 200 lines are there right away, new ones keep coming. If the editor finds no log, it says "No log found".
The proxy only offers Start and Restart, an own process has no Restart.
Show and hide
- Settings › Features › Status bar: turn off WebDonkey and the project's site, Open in browser and Update notice one by one, and the other status bar entries as well.
- Settings › Services › The site's services in the status bar: the service dots.
- Settings › Features › More features › Services in the editor turns off the status bar item, the terminal badge, checking on save and the service configs in the WebDonkey window all at once.
Free and Premium
The status bar is free. Follow log in the terminal is part of Premium. On Free the entry reads "Follow log (Premium, opens WebDonkey)" and opens WebDonkey's Logs page.
See also
Open in WebDonkey Free
The editor and WebDonkey work together: whatever the editor does not show itself, it opens at the right place in WebDonkey, and from WebDonkey and the terminal you get straight back into the editor. This page collects the ways in both directions.
From the editor to WebDonkey
| Where | Button | Where to |
|---|---|---|
| WebDonkey window, header | Show in WebDonkey (arrow) | WebDonkey's dashboard. |
| WebDonkey window, header | Start WebDonkey | Starts WebDonkey when it is not running. If it is not installed: "WebDonkey isn't installed on this Mac. You can get it at shop.webdonkey.io." |
| WebDonkey window, logs (Free) | Click a log | WebDonkey's Logs page. |
| WebDonkey window, workflows | Start in WebDonkey | WebDonkey's Workflows, for workflows that need input. |
| Status bar, services (Free) | Follow log (Premium, opens WebDonkey) | WebDonkey's Logs page. |
| AI window, Ollama is not running | Open AI page in WebDonkey | The models on WebDonkey's AI page. |
| AI window | Install in WebDonkey | WebDonkey's AI page at Ollama or the selected agent CLI. WebDonkey starts for this if it is not running. |
| Status bar, AI | Load a model in WebDonkey | The models on WebDonkey's AI page. |
| Claude window | Open the Claude page in WebDonkey | WebDonkey's Claude page. |
If WebDonkey is not running, the log links open shop.webdonkey.io in the browser instead.
From WebDonkey and from outside into the editor
- Open as project in a site row of the WebDonkey window makes the site's project folder the project, see Sites.
- The editor's start screen lists your sites under From WebDonkey. A click opens the site's project folder. You turn that off under Settings › Features › Sites from WebDonkey on the start screen.
- In the terminal,
wd edit <file>opens a file in the editor, in the window of the project the file belongs to, otherwise in the one used last.wd edit --wait <file>waits until you close the tab. That is whyEDITORis set towd edit --waitin the editor's terminals, sogit commitor Claude Code's Ctrl+G open a tab. - If the editor keeps running in the background with Keep running when the window is closed, the Dock icon or
wd editbring the window back.
When WebDonkey is too old
If the editor needs a newer WebDonkey, it works as if WebDonkey were not there and asks you to update WebDonkey. Once the updated WebDonkey has converted its data, the editor connects by itself, without a restart.
Without WebDonkey
Without WebDonkey, editor, files, terminal and Git work as usual. Remote, databases, themes and notes work with your Premium key, which you enter in the editor. Whatever needs sites and local services, that is the WebDonkey window, the status bar entries, shims and Mailpit, only works with WebDonkey.