Dev servers

A dev server in mocante is a tab of a session, like an agent. mocante recognizes servers you start yourself, runs the ones your project declares, and lists them all with their state, their port and buttons to start, stop and restart them.

Each server runs in a window of the session’s tmux session. It keeps running when you restart mocante, you can type into it (for example Vite’s r), and it stops when you close the session. A worktree session serves its own worktree, so two sessions of one repository each run their own server.

What mocante recognizes

A tab is a dev server when no agent runs in it and one of these is true:

• It listens on a TCP port. This works for any server, with no setup.
• mocante started it from the project’s declaration. It stays in the list even while it is stopped or has crashed, so you can start it again.
• Its output says it is serving, such as Local: http://… or ready in, and its command is a typical server command such as node, pnpm, python3, rails or docker.

A server you did not declare appears once it comes up, and disappears again after it crashes and its ready line scrolls away. Declare it to keep it listed.

A tab that runs an agent is never a dev server, even when the agent listens on a port.

States

State	Meaning
listening	A port is open, or the output says the server is ready.
compiling	The output says it is building, bundling or restarting right now.
starting	Something runs, but no port is open and nothing is ready yet.
crashed	The output ends in an error and no port is open.
stopped	A declared server whose tab is back at the shell prompt.

A crashed or compiling server shows the line of output that says so.

The address

When a server prints its own URL, mocante uses it. Otherwise it uses the first open port. 0.0.0.0 becomes localhost.

Declare a server for the project

A declaration belongs to the project, so every workspace and session of the project offers the same servers. It is part of the synced configuration, so your other devices get it too.

1. Run Declare a dev server from the palette, or select + in the dev servers pane.
2. Under Found in this project, pick a script that mocante read from package.json, a Procfile or a compose file. It fills in the fields with the package manager your lockfile uses.
3. Check the fields:
   • Name names the tab and the card.
   • Command is one line that mocante types into the tab’s shell.
   • Folder is relative to the session’s folder. Leave it empty for the root, or set it for a server inside a monorepo, such as apps/web.
   • Port is only a fallback for Open until mocante sees the real port.
   • Start with new sessions starts the server in its own tab when mocante creates a session in this project.
4. Select Add server.

To change or remove a declaration later, use Edit this server or Remove from the project on its card.

Start, stop and restart

• Start opens a tab, names it and types the command.
• Stop sends Ctrl+C and leaves the tab and its output in place.
• Restart sends Ctrl+C, waits for the shell prompt to come back, then types the command again. The tab keeps its place.
• Open shows the server’s page in the session’s built-in browser.
• Logs takes you to the server’s terminal tab.

The palette has Start a dev server, Stop a dev server, Restart a dev server and Open a dev server in the browser.

Note

You can stop a server you started by hand, but not restart or start it again, because mocante does not know its command. Declare it to get all the buttons.

See your servers

Beside a session

The dev servers pane shows one card for each declared server and each server the session runs, with its state, ports, the line that explains a crash, and the buttons. Open it with Show dev servers in the palette. See panes for placing it.

The button that shows the pane carries a dot in the color of the worst state among the session’s servers, so you notice a crash while the pane is hidden. Each server’s tab in the terminal tab strip carries the same dot.

Across the fleet

The fleet view lists every running server on every host above the agents, with its session, state, address and host. Declared servers that are not running are not listed there; start them from their session.

On a remote host

Open works the same for a session on a remote host: localhost in that session means the host, and the browser reaches it over ssh.

mocante finds ports with ss, or lsof where ss is missing. On a host with neither, mocante sees no ports and relies on the server’s output alone.

Let the agent use them

The agent in a session can list the session’s servers with their addresses, read a server’s recent output, and restart or start one. That lets an agent use the server that is already running instead of starting its own pnpm dev and waiting on a process that never exits. Restarting asks for your approval the first time. See agent tools.