# 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](https://testlane.dev/docs/configuration/overview) 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

::steps{level="3"}

### Hand the port to your app

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

```toml [~/.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

```bash
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

```bash
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

```bash
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:

```toml [~/.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:

```bash
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:

```toml [~/.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`:

```bash
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`:

```bash
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:

- [Environment and templates](https://testlane.dev/docs/configuration/environment-and-templates) lists every template variable and `TESTLANE_*` variable.
- [Project file](https://testlane.dev/docs/configuration/project-file) has `ports`, `base_port` and `[env]` with the rest of the keys.
- [Use Testlane from an agent](https://testlane.dev/docs/guides/use-testlane-from-an-agent) shows how `start` leaves a server running on its port and hands back its URL.
