> ## 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.

# toolkit run — Launch Dev Servers with Proxy Domains

> toolkit run <appName> <cmd> starts your dev server and automatically maps it to http://<appName>.localhost — no manual proxy registration needed.

`toolkit run` is the primary workflow command for local development. It launches your dev server process and simultaneously registers a `*.localhost` proxy route for it — so your app is immediately available at a clean, memorable URL like `http://my-app.localhost` without you ever touching a port number in the browser. When you stop the process, the proxy route is automatically cleaned up.

Under the hood, `toolkit run` starts the proxy daemon if it is not already running, detects (or assigns) an internal port for your process, spawns the command you provide, and maps the chosen subdomain to that port in a single step.

**Syntax**

```bash theme={null}
toolkit run <appName> <cmd...> [options]
```

**Arguments**

| Argument    | Type       | Required | Description                                                                                                            |
| :---------- | :--------- | :------- | :--------------------------------------------------------------------------------------------------------------------- |
| `<appName>` | `string`   | Yes      | Subdomain name for the proxy route. For example, `dashboard` makes your app available at `http://dashboard.localhost`. |
| `<cmd...>`  | `string[]` | Yes      | The full command to run, including all its arguments (e.g., `npm run dev`, `vite`, `python -m http.server 8000`).      |

**Options**

| Option                | Type     | Default       | Description                                                                                                          |
| :-------------------- | :------- | :------------ | :------------------------------------------------------------------------------------------------------------------- |
| `-p, --port <number>` | `number` | Auto-assigned | Force the internal port that the local process will listen on. Useful when your dev server requires a specific port. |

**Examples**

```bash theme={null}
# Start a Next.js app — available at http://dashboard.localhost
toolkit run dashboard npm run dev

# Start a Vite app, forcing the internal port to 5173
toolkit run my-landing vite --port 5173

# Serve Python docs via the built-in HTTP server on port 8000
toolkit run api-docs python -m http.server 8000

# Start a Create React App project on a fixed port
toolkit run frontend npx react-scripts start --port 3000
```

<Info>
  When you stop the process (Ctrl+C), the proxy route is automatically removed. You do not need to run `toolkit proxy remove` manually after each session.
</Info>