> ## Documentation Index
> Fetch the complete documentation index at: https://toolkit.astralsolutions.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Multiple Dev Servers on Clean Local Domain Names

> Use Toolkit's reverse proxy to assign *.localhost subdomains to each of your local dev servers — no port numbers, no browser config, no sudo required.

Keeping track of `localhost:3000`, `localhost:8080`, and `localhost:5173` across a multi-service project is a recipe for confusion. You paste the wrong URL into a browser tab, your teammates get mismatched environments, and your proxy config in each framework adds yet another moving part. This guide shows you how to assign clean, memorable domain names — `http://frontend.localhost`, `http://api.localhost`, and `http://admin.localhost` — to each of your local dev servers using Toolkit's built-in reverse proxy. No port numbers, no browser extensions, and no `sudo` required.

## The Scenario

You're working on a project with three services running simultaneously:

* **Next.js frontend** — started via `npm run dev`, listens on a dynamic port
* **Node.js API** — started via `node server.js`, listens on port 4000
* **Python docs server** — started via `python -m http.server 8000`

Instead of juggling three different port numbers, you'll expose each service on its own `.localhost` subdomain.

## Start Your Services with Clean Domains

<Steps>
  <Step title="Start the Next.js frontend">
    Use `toolkit run` to launch your frontend and register it under `http://frontend.localhost` automatically. Toolkit detects the port your dev server binds to and wires up the proxy route for you.

    ```bash theme={null}
    toolkit run frontend npm run dev
    ```

    Toolkit spawns your process, watches for the listening port, and registers `frontend` as a proxy subdomain — all in one command.
  </Step>

  <Step title="Start the Node.js API">
    Launch your API server the same way. Use the name `api` to expose it at `http://api.localhost`.

    ```bash theme={null}
    toolkit run api node server.js
    ```
  </Step>

  <Step title="Start the Python docs server">
    Start the Python HTTP server and register it under `http://docs.localhost`.

    ```bash theme={null}
    toolkit run docs python -m http.server 8000
    ```
  </Step>

  <Step title="Verify all proxy routes">
    Confirm that all three services are registered and active by listing the current proxy routes:

    ```bash theme={null}
    toolkit proxy list
    ```

    You should see output similar to:

    ```
    ┌─────────────┬─────────────────────────────────┬─────────────┐
    │ Subdomain   │ URL                             │ Target Port │
    ├─────────────┼─────────────────────────────────┼─────────────┤
    │ frontend    │ http://frontend.localhost       │ 3000        │
    │ api         │ http://api.localhost            │ 4000        │
    │ docs        │ http://docs.localhost           │ 8000        │
    └─────────────┴─────────────────────────────────┴─────────────┘
    ```
  </Step>

  <Step title="Open each service in your browser">
    Navigate directly to each service using its clean `.localhost` URL — no port number needed:

    * **Frontend:** [http://frontend.localhost](http://frontend.localhost)
    * **API:** [http://api.localhost](http://api.localhost)
    * **Docs:** [http://docs.localhost](http://docs.localhost)

    All three URLs resolve to `127.0.0.1` natively in every modern browser, in full compliance with [RFC 6761](https://datatracker.ietf.org/doc/html/rfc6761). No hosts file edits, no browser flags.
  </Step>
</Steps>

## Manual Registration

If you already have a server running on a specific port and want to register a proxy route without restarting it, use `toolkit proxy add`:

```bash theme={null}
toolkit proxy add <subdomain> <targetPort>
```

For example, to expose an existing server running on port 4000 at `http://backend.localhost`:

```bash theme={null}
toolkit proxy add backend 4000
```

This is useful when you start services outside of Toolkit — for example, from inside an IDE terminal or via a `Makefile` target.

## Removing a Route

To deregister a proxy route when you're done with a service, use `toolkit proxy remove`:

```bash theme={null}
toolkit proxy remove frontend
```

The subdomain is immediately released. The underlying process is not killed — only the proxy route is removed. Run `toolkit proxy list` to confirm the route is gone.

## WebSockets and HMR

<Info>
  All proxy routes created by Toolkit support WebSockets and Hot Module Replacement (HMR) automatically. Your Next.js or Vite dev server's hot-reload functionality will work exactly as expected through the `.localhost` URL — no additional configuration needed in `next.config.js`, `vite.config.ts`, or anywhere else.
</Info>

## Open the Dashboard Automatically on Login

<Tip>
  Use `toolkit autostart enable --mode browser_launch` to have the Toolkit dashboard open automatically in your browser with all your proxy routes ready each time you log in. Combined with `toolkit run` for your services, your entire dev environment can come online at startup without any manual steps.

  ```bash theme={null}
  toolkit autostart enable --mode browser_launch
  ```
</Tip>