Skip to content
Source
Sign inSign up

Give each workspace its ports

Work with agents / Local workspaces

Give each workspace its own ports

Two agents that run pnpm dev at the same time both ask for port 5173, and the second one fails. src ws gives each workspace its own block of 10 ports, and src ws exec puts them in the variables that your tool reads.

2 min read

1. Make your tool read its port from a variable

For Vite:

export default { server: { port: Number(process.env.PORT ?? 5173) } }

Tip

src ws init looks for ports that your config files set as numbers: vite.config.*, next.config.*, wrangler.toml, wrangler.json, wrangler.jsonc, and --port <n> or -p <n> in the scripts of package.json. It lists each one with its file and line. Change those to read a variable.

2. Name the port in the config

In .source/workspace.yaml:

ports:
  web:
    default: 5173
    env: PORT
  api:
    default: 8787
    env: API_PORT

3. Trust the config

src ws trust

The variables of the ports are commands of the config, so they need your trust.

4. Run the tool in a workspace

src ws exec api -- pnpm dev

exec prints the ports of the workspace on stderr:

Ports of api: web 5173 -> 10240 (PORT), api 8787 -> 10241 (API_PORT), SRC_WS_PORT_0..9 = 10240-10249

Done

Each workspace runs its dev server on its own port, and the second agent no longer fails on a busy port.

How the ports work

  • The first named port gets the first port of the block, the next one the second, and so on. You can name up to 10.
  • exec also sets SRC_WS_PORT_0 to SRC_WS_PORT_9 to the 10 ports of the block, with or without the ports section.
  • The blocks start at port 10000. To start them at another port, set SRC_WS_PORT_START.
  • Two open workspaces never get the same block. A block in which a port is busy when create runs is skipped. close gives the block free.
  • src ws list shows the block in the PORTS column, and --json ports gives the block with its named ports.