Guides

Run Dev Servers in Parallel

Give every workspace its own ports, so two branches run their dev servers side by side without fighting over one.

By the end of this guide, two branches of the same project run their dev servers at the same time, each on a port of its own. Testlane gives every workspace its own block of ports and keeps it for the workspace's life, so all you do is tell your app which variable to read.

Before you start

You'll need a configured project with a [commands.dev] entry whose server reads its port from an environment variable, like PORT. We'll call the project my-project.

Run two branches at once

Hand the port to your app

Map the workspace's port onto the variable your app reads, with the {port} template variable in [env]:

~/.testlane/my-project.toml
[env]
PORT = "{port}"

[commands.dev]
run = "pnpm dev"

Testlane also exports the port as $TESTLANE_PORT to every command, whether or not your config uses it. [env] is how you give it the name your app expects.

Start the first branch

testlane my-project feat/login run dev
→ fetching origin/feat/login
→ worktree ready: /home/you/dev/testlane/my-project/trees/feat-login
→ running setup
…
listening on 4153

run keeps your terminal while the server runs, so open a second one for the next step.

Start the second branch

testlane my-project feat/search run dev
→ fetching origin/feat/search
→ worktree ready: /home/you/dev/testlane/my-project/trees/feat-search
→ running setup
…
listening on 4160

Each workspace got its own port, so both servers are up at once.

See which port each one holds

testlane my-project list
SLUG         KIND    BRANCH       STATUS  PORT  AGE  LAST USED
feat-search  branch  feat/search  clean   4160  0m   0m
feat-login   branch  feat/login   clean   4153  0m   0m

For one workspace in a script, testlane my-project feat/login info --json prints its ports as an array.

Give a workspace several ports

An app with a web server, an API and a database needs a port for each. Set ports to the size of the block, and refer to the others as {port+1}, {port+2} and so on:

~/.testlane/my-project.toml
base_port = 5700
ports = 3

[env]
PORT = "{port}"
API_PORT = "{port+1}"
DB_PORT = "{port+2}"
VITE_API_URL = "http://localhost:{port+1}"

ports takes 1 to 10, and {port+N} works for any N below ports. Your commands also get the block as $TESTLANE_PORT, $TESTLANE_PORT_1 and $TESTLANE_PORT_2.

Keep in mind that testlane config validate checks the value of ports, but not your template variables. A {port+3} with ports = 3 fails when a command runs, with E_CONFIG (exit 3):

error(E_CONFIG): env.DB_PORT: unknown template variable '{port+3}'
hint: known variables: branch, data_dir, path, port, port+1, port+2, project, ref, repo_path, slug

When you raise ports, we recommend setting base_port too, as above. Without it, Testlane picks a base port for each project from its name, 100 apart, which fits one port per workspace but lets bigger blocks run into the next project's ports.

Keep in mind that a workspace keeps the block it got when it was created, so new ports and base_port values apply to new workspaces only. A workspace that already exists fails with unknown template variable '{port+1}' until you create it again:

testlane my-project feat/login sync --fresh

Pin the base port

base_port is where a project's ports start. Pin it when you want the same ranges on every machine of a team, or to keep two projects apart:

~/.testlane/my-project.toml
base_port = 5700
ports = 2

It takes 1024 to 65000. Each workspace starts from a port worked out from its slug, within 100 blocks above base_port, and moves up a block only when that one is taken by another workspace or something already listens on it. So a branch gets the same port every time you open it, and bookmarks and OAuth callback URLs keep working.

Change the port for one run

When something else holds a workspace's port for a while, or you want to try another one, you can override it for a single run:

testlane my-project feat/login run dev --port 6000

--port changes the first port for this run only. Nothing is saved, and the workspace keeps its block. Note that start doesn't take --port, since the process it leaves running always serves the workspace's own port, so ps and your hooks agree on it.

See what your app gets

To see the environment a command would get, without running anything, add --dry-run:

testlane my-project feat/login run dev --dry-run
…
export TESTLANE_PATH=/home/you/dev/testlane/my-project/trees/feat-login
export TESTLANE_REPO_PATH=/home/you/dev/testlane/my-project/repo
export TESTLANE_DATA_DIR=/home/you/dev/testlane/my-project/trees/.data/feat-login
export TESTLANE_PROJECT=my-project
export TESTLANE_REF=feat/login
export TESTLANE_BRANCH=feat/login
export TESTLANE_SLUG=feat-login
export TESTLANE_PORT=4153
export PORT=4153
bash -c 'pnpm dev "$@"' testlane

It prints the git commands it would run, every variable as an export line and then the command itself. Note that the port it shows is the one worked out from the slug, which is the workspace's own port unless that one was taken when the workspace was created, so list is where to check a port. The lines left out above are the git plan.

Where to go next

Here's where to go from here:

Copyright © 2026