Repository navigation
Releases
v0.11.3
- Dialogs: Escape closes the "Discard changes?" prompt and leaves Settings open (the same for the config editor); before, it opened the prompt again. In Chrome and other Chromium browsers, pressing Escape again without a click no longer hides a dialog the dashboard still showed as open, which left the page unresponsive.
- Settings: in the macOS app, Appearance shows the app icon chosen in the menu bar app's menu, also when it changed while the dashboard was open.
Install
With Homebrew on macOS 26 or later (Apple Silicon), the app and the command:
brew install --cask padmk/tap/portsideOn macOS or Linux (x86-64, arm64), the command and dashboard, built from source:
brew install --formula padmk/tap/portsidePortside-0.11.3.zip below is the same app, and the portside_*.tar.gz archives hold the command alone. See the README for details.
v0.11.2
- Settings, reorganized: a larger window whose sections fit without scrolling in the app's window, each a few groups of rows (label and explanation on the left, control on the right): General (startup, projects folder, editor, terminal, language), Appearance (mode, a one-row palette, layout and, in the macOS app, the app icon), Servers, Events, Environment, Coding agents and Advanced. Save stays in the footer on every section and says when there are unsaved changes, and closing with unsaved changes asks first.
- Settings, new: the dashboard's
portcan be set (empty lets the daemon choose; it applies after a daemon restart), and Advanced has the config file (edit it in the dashboard or open it in your editor), the server logs folder and Computers (Settings and the server form).
Install
With Homebrew on macOS 26 or later (Apple Silicon), the app and the command:
brew install --cask padmk/tap/portsideOn macOS or Linux (x86-64, arm64), the command and dashboard, built from source:
brew install --formula padmk/tap/portsidePortside-0.11.2.zip below is the same app, and the portside_*.tar.gz archives hold the command alone. See the README for details.
v0.11.1
- Every setting in the dashboard: Settings has sections (General, Servers, Environment, Events, Docker, Coding agents) that edit the config file's top-level keys, from the projects folder,
restoreandnotifytopath,env,login_env,umask, the hook commands anddocker_start, with one Save, the daemon's errors, defaults as placeholders and the daemon's version in the footer. Onlyportstays in the file. A server's form has It's a task (runs once) and an Advanced section with every other server key:ready_log,ready_after,stop_timeout,retry_after,memory_limit,enabled,schedule,watch, the hook commands,unready_after,wrap,umask,lan,open,iconandprojects. Saves change only the keys you edited and keep your comments; a value set back to its default is removed (Settings and the server form). - Settings: the dashboard's Settings has Startup with Start Portside at login in the macOS app (in a browser, the
portside service installcommand), so the setting is no longer only in the menu bar app's menu and on the getting-started page.
Install
With Homebrew on macOS 26 or later (Apple Silicon), the app and the command:
brew install --cask padmk/tap/portsideOn macOS or Linux (x86-64, arm64), the command and dashboard, built from source:
brew install --formula padmk/tap/portsidePortside-0.11.1.zip below is the same app, and the portside_*.tar.gz archives hold the command alone. See the README for details.
v0.11.0
- Crashed servers start again by default. A server without a
restartsetting now useson-failure: after a crash it starts again with backoff (1, 2, 4, 8 and 16 s), and only after 5 restarts in a row does it staycrashedand get reported. Tasks (oneshot = true) still default tono, so a failed migration is reported at once rather than repeated. To keep the old behavior for a server, setrestart = "no"; the dashboard's form now writes that choice explicitly. - Getting started: in the macOS app, the dashboard's getting-started page offers Start Portside at login, on until you have chosen once (there or in the app's menu) and applied when you find projects or add a server, so your servers come back after a restart. In a browser it shows
portside service installinstead. - Settings shortcut:
⌘,(Ctrl+, outside macOS) opens Settings in the dashboard, and the app menu has Settings… with⌘,.
Install
With Homebrew on macOS 26 or later (Apple Silicon), the app and the command:
brew install --cask padmk/tap/portsideOn macOS or Linux (x86-64, arm64), the command and dashboard, built from source:
brew install --formula padmk/tap/portsidePortside-0.11.0.zip below is the same app, and the portside_*.tar.gz archives hold the command alone. See the README for details.
v0.10.2
- Fixed, tasks:
portside restartof a task (alone, with other servers, from the dashboard orrestart_server) runs it again instead of leaving it stopped. After an upgrade in place, a server that was waiting for a task whose process ended during the upgrade fails with the task's note instead of running the task a second time. - Fixed: a server whose process exits while the daemon upgrades in place continues its round of automatic restarts instead of starting a new one, so
on_crashreports it after the same number of restarts as without the upgrade. A start no longer races with a config reload over the server's dependencies. - Fixed, dashboard: saving a server's form refuses with a conflict when the config file was changed at the same moment from the CLI or an editor, instead of overwriting that change.
- Fixed, MCP: with
--dir,list_portsno longer shows another program that took the port of a stopped server in scope.
Install
With Homebrew on macOS 26 or later (Apple Silicon), the app and the command:
brew install --cask padmk/tap/portsideOn macOS or Linux (x86-64, arm64), the command and dashboard, built from source:
brew install --formula padmk/tap/portsidePortside-0.10.2.zip below is the same app, and the portside_*.tar.gz archives hold the command alone. See the README for details.
v0.10.1
watch: a server with many watched files is scanned less often instead of costing more, about 2 % of one core at most for all servers together, and a large tree slows only its own server; a change among 20,000 files takes a few seconds to notice (Periodic checks).**also skipsvenv.portside checkcounts a task as healthy while its process runs (not while it waits for its dependencies), so a long scheduled task no longer fails a monitor's check; a task you name must still be done.- Fixed: a stop asked for while the daemon upgrades in place (about a second) is refused with a message to try again, instead of being lost or counted as a crash by the new daemon. Two servers that need the same task, started at once, no longer run it twice.
- Fixed, tasks: servers started together share a task's run also when it fails, instead of running it again; a task started as a dependency gets a fresh round of automatic restarts; a
watchrestart of a task or server no longer fails the servers andensurecalls waiting for it. - Fixed, schedules: rare dates such as a Sunday 29 February are found (the next run is searched across 400 years, not 10), and the dashboard names the right day for a run just after a clock change.
- Menu bar app: counts servers only, as the dashboard does, so a running task no longer keeps the icon amber as a server still starting.
- Security docs: a server with
watchruns whatever is saved in its watched files, whatever an agent's MCP mode or--dirscope (Security).
Install
With Homebrew on macOS 26 or later (Apple Silicon), the app and the command:
brew install --cask padmk/tap/portsideOn macOS or Linux (x86-64, arm64), the command and dashboard, built from source:
brew install --formula padmk/tap/portsidePortside-0.10.1.zip below is the same app, and the portside_*.tar.gz archives hold the command alone. See the README for details.
v0.10.0
- Tasks:
oneshot = truemakes an entry a task that runs to completion, such as a migration. Servers thatdepends_onit start once it exits with code 0, and arecrashedwith a note such asdependency migrate failed: exited with code 1when it fails.ensure,up --waitandensure_serverrun the task again and wait for its end; servers started together share one run. A task has no port, shows as done after a successful run, and counts forportside checkonly while it runs, when it failed, or when you name it (Tasks). - Schedules:
schedule = "30 2 * * *"starts a task or server at the times a crontab expression matches, in local time (five fields, names, ranges, lists, steps and@dailystyle macros). A run missed during sleep or while the daemon was down happens once afterwards, a server still running skips the run,PORTSIDE_TRIGGERisschedule, andenabled = falsepauses it.portside status, the dashboard andlist_serversshow the next run (Schedules). memory_limit(top level or per server, such as"2GB";"0"turns an inherited one off) stops a server whose processes use more memory, checked with each usage sample (every 30 seconds, every 2 seconds while the dashboard shows usage). It counts as a crash with a note such asused 2.3 GB, over memory_limit 2 GB: the restart policy applies andon_crashgets the note. Worktree copies have their server's limit; containers are not covered (Memory limit).watch = ["src/**/*.py", "pyproject.toml"]restarts a server once changes to the files it matches, relative to itsdir, have stopped for about a second, and starts a crashed one again after a change, so fixing the error brings it back. The log names the change (restarting: changed src/app.py (+3 more)) andPORTSIDE_TRIGGERiswatch. A server you stopped ignores changes, and a task restarts only while it runs. Files are polled every second, only in directories a pattern can match, skipping.git,node_modulesand similar folders unless a pattern names them. The dashboard marks such a server watching (Restart on file changes).- Hook commands:
PORTSIDE_TIMEgives when the event happened (RFC 3339), so a monitor can order reports whose commands finished out of order. - Fixed: an automatic restart still waiting for its backoff when the daemon upgraded in place was lost with
restore = false, or happened at once with a fresh count of restarts; it now happens at its time in the new daemon and continues the count, unless the config the new daemon loads setsrestart = "no". - Fixed: a server that was still starting when the daemon upgraded in place no longer stays down with
restore = false, nor when the upgrade fails: the start goes on.
Install
With Homebrew on macOS 26 or later (Apple Silicon), the app and the command:
brew install --cask padmk/tap/portsideOn macOS or Linux (x86-64, arm64), the command and dashboard, built from source:
brew install --formula padmk/tap/portsidePortside-0.10.0.zip below is the same app, and the portside_*.tar.gz archives hold the command alone. See the README for details.
v0.9.0
- Hook commands:
on_unreadyruns when a running server has not answered on its port orhealthpath forunready_after(a minute unless set), andon_recoverwhen a server thaton_crashoron_unreadyreported is ready again, withPORTSIDE_RECOVERED_FROMandPORTSIDE_DOWNTIME. Likeon_crash, both are set at the top level or per server, and one script can tell the events apart byPORTSIDE_EVENT. - Crash command:
PORTSIDE_STREAKcounts the crashes for good in a row without the server being ready in between, so a monitor that starts failed servers again can report each problem once, andPORTSIDE_TRIGGERsays what began the run (startorrestore). The streak and an open problem survive daemon restarts and upgrades. umask(top level or per server) sets the mode mask for the files a server creates, such as"0007"; without it servers keep the daemon's, which launchd and systemd set to0022, readable by other accounts.login_env = falsegives servers the daemon's own environment pluspathandenvinstead of the login shell's, for servers whose environment the config alone should decide.portside doctorsays which one servers get.retry_after(top level or per server, forrestart = "on-failure"or"always") starts a server again that long after its automatic restarts gave up or its start failed, with another 5 restarts, until it runs or you stop it;PORTSIDE_TRIGGERis thenretry. The dashboard offers Stop while it waits, and the menu bar app still announces the crash.- Docs: the Linux server guide explains that
systemctl --user restart portsidestops every server, whileportside daemon restartkeeps them running.
Install
With Homebrew on macOS 26 or later (Apple Silicon), the app and the command:
brew install --cask padmk/tap/portsideOn macOS or Linux (x86-64, arm64), the command and dashboard, built from source:
brew install --formula padmk/tap/portsidePortside-0.9.0.zip below is the same app, and the portside_*.tar.gz archives hold the command alone. See the README for details.
v0.8.0
- MCP
--dirscope: a container counts as a scoped server's only through the server'sprojectsin the config or a Compose working directory inside the scope, so a project'ssupabase/config.tomlnaming another project's ID no longer exposes that project's containers; a Supabase CLI project ID listed in a server'sprojectsbelongs to that server alone, also on the dashboard. Containers andlist_portsno longer name a server outside the scope, andensure_serverrefuses adiroutside it. - Worktree copies:
dirmust be a worktree git has registered for the repository; a directory whose.gitfile only points into the repository is refused. - MCP: program output quoted by
ensure_serverandrestart_servererrors and bycontainer_actionis marked as untrusted. The docs say plainly thatstartandfullmodes run code the agent can edit. - Security, sharing: unpairing a device, or pairing it again, now also refuses its request whose body was still arriving and ends every connection of the old pairing; the body of a paired device's request must arrive within 30 seconds. On Linux the sharing listener accepts connections only from root or your own account, which
tailscaledruns as, so other local accounts that read the Serve path cannot send it forged Tailscale headers. - Security, sharing: a reply relayed from the connected computer is cut off at 64 MiB, since the daemon may hold a whole reply to sign it for the CLI, so a computer that was taken over cannot exhaust this one's memory.
- Security, sharing: this daemon never follows a redirect from the connected computer, cuts off a relayed reply that stops for a minute, ignores a state that is not a JSON object, and opens that computer's server addresses only on this computer, at the forwarded port or through the proxy, whatever host they name; the dashboard ignores a state of another shape than it reads.
- Security: the CLI and the macOS app never follow a redirect from what answers on the daemon's port, for requests and WebSockets alike, which could have sent a signed request elsewhere before its reply was checked; writes need an
Originthat is a plain origin (no user, path or query). - CLI and MCP: names, notes and commands are printed with control characters replaced in tables, and the list tools tell agents that these fields are data, not instructions.
- Security, pairing:
portside pair <computer>reads the code from standard input (it asks on a terminal, or reads a pipe); the code as an argument, which other accounts could read and redeem first, is refused. - Security, forwarded ports: forwarded ports hold at most a quarter of the daemon's open-file limit (about 11,000 ports on a Mac, all of them on Linux), servers first; ports beyond it are listed as over the limit in the Computers window,
portside computersandportside doctor, and turning a port off makes room. Binding forwarded ports and checking them for local listeners happen outside the lock other requests wait for, at most 128 every 2 seconds, so thousands of ports no longer stall the dashboard; a local server starting on a port that is being bound gets it, and the dropped bind never forwards a connection. This computer never listens for a forwarded port on the daemon's own, default or fallback ports; such a remote port is listed as busy and can go to another local port. - Fixed: starting a server while it is still stopping (
portside downand thenensure, orensure_serveranddepends_onmeanwhile) starts it again once its whole process group has exited, so a child still holding the port does not block it, also when the server exits just as the start arrives or is renamed meanwhile, instead of leaving it stopped untilensuretimed out. - Fixed: a daemon start after a stop no longer ends a process group whose id another program got in the meantime: a stopping daemon removes its servers' groups from the state once they have exited, and after a crash a leftover group is ended only when its processes can be tied to the server.
- Fixed: an upgrade in place is refused until a stopping server's processes have all exited, also after its main process did, so the upgrade no longer cuts the stop short and leaves a child running.
- Fixed: a server that exits while the daemon upgrades in place counts as crashed, so its restart policy or
on_crashapplies, instead of counting as stopped; withrestart = "no"it stays down also whenrestorebrings back the other servers. - Fixed: shutting the daemon down while a server stops no longer sends it a second
Ctrl-C, which madedocker composeabort its graceful stop, and waits until that stop has ended every process the server started, also for a server removed from the config meanwhile; a secondportside downalso waits for it, and no restart stays announced for a server that crashed just before. - Fixed: an
on_crashcommand that leaves a background process holding its output no longer runs forever and takes one of the four slots. - Fixed:
ready_logand plain logs strip color sequences with:parameters, such as\x1b[4:3m(curly underline), so an anchoredready_logmatches. - Fixed: a state file that cannot be written (for example a read-only state directory) is reported in the daemon log and as a warning in the dashboard and
portside doctor, instead of silently losing which servers you stopped. portside daemon infoincludesconfigErroralso when a running daemon goes on with the last config that loaded.- Fixed: turning a server on or off in the config keeps a comment on the
enabledline, edits keep the blank lines that end the file, a key written in another case (Enabled) is edited in place, and a server table with two keys that differ only in case (cmdandCmd) is refused instead of loading either. - Linux is a first-class platform (x86-64, arm64), next to macOS: CI runs the systemd user service end to end and an upgrade from the latest release on every change, and the README installs it with the same Homebrew tap (
brew install --formula padmk/tap/portside) or from the release archives.
Install
With Homebrew on macOS 26 or later (Apple Silicon), the app and the command:
brew install --cask padmk/tap/portsideOn macOS or Linux (x86-64, arm64), the command and dashboard, built from source:
brew install --formula padmk/tap/portsidePortside-0.8.0.zip below is the same app, and the portside_*.tar.gz archives hold the command alone. See the README for details.
v0.7.2
- Dashboard, menu bar and CLI: a running server that stopped answering on its port or
healthpath shows as not responding (an amber diamond in the dashboard, an orange light in the menu bar, a yellow dot inportside status) and is counted apart from the running ones, asportside checkalready reported it. - Upgrades in place: the upgrade is refused, and the servers keep running under the current daemon, when the terminal of a server still waiting for its
ready_logline cannot be paused, so that line cannot slip between the two daemons; for other servers it is only logged. - CI: the Linux service run also upgrades the daemon while a server is still waiting for its
ready_logline, and both Linux and macOS upgrade the latest published release in place to the new build (scripts/upgrade-from-release.sh).
Install
macOS 26 or later on Apple Silicon:
brew install --cask padmk/tap/portsidePortside-0.7.2.zip below is the same app. The portside_*.tar.gz archives hold the command-line binary alone (Linux is a preview). See the README for details.