> ## 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 proxy — Manage Local *.localhost Proxy Routes

> toolkit proxy list, add, and remove commands — view, register, and delete *.localhost subdomain routes pointing to local dev server ports.

The `toolkit proxy` command group lets you manage the reverse proxy routes that map clean `*.localhost` subdomains to local dev server ports. It exposes three subcommands: `list` to display every currently registered route, `add` to manually register a new subdomain pointing to an existing local port, and `remove` to unregister a route you no longer need. Routes registered here are served by the toolkit proxy daemon at `http://<subdomain>.localhost`.

<Note>
  The proxy daemon must be active for routes to resolve in the browser. Start it with `toolkit daemon` or enable autostart with `toolkit autostart enable`.
</Note>

***

### toolkit proxy list

Display all active `*.localhost` proxy routes currently registered in the system, including their target ports and associated application names.

**Syntax**

```bash theme={null}
toolkit proxy list [options]
```

**Options**

| Option   | Type      | Default | Description                                       |
| :------- | :-------- | :------ | :------------------------------------------------ |
| `--json` | `boolean` | `false` | Emit the list of proxy routes as structured JSON. |

**Examples**

```bash theme={null}
# Print all registered proxy routes in a human-readable table
toolkit proxy list

# Emit routes as JSON for scripts or monitoring tools
toolkit proxy list --json
```

***

### toolkit proxy add

Manually register a `*.localhost` subdomain route that forwards traffic to an existing local port. Use this when you want to expose a dev server that is already running without going through `toolkit run`.

**Syntax**

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

**Arguments**

| Argument       | Type     | Required | Description                                                                      |
| :------------- | :------- | :------- | :------------------------------------------------------------------------------- |
| `<subdomain>`  | `string` | Yes      | Subdomain name to register (e.g., `backend` becomes `http://backend.localhost`). |
| `<targetPort>` | `number` | Yes      | Local internal port to which incoming requests will be forwarded (e.g., `4000`). |

**Options**

| Option   | Type      | Default | Description                                 |
| :------- | :-------- | :------ | :------------------------------------------ |
| `--json` | `boolean` | `false` | Emit the registration confirmation as JSON. |

**Examples**

```bash theme={null}
# Register http://api.localhost -> http://127.0.0.1:4000
toolkit proxy add api 4000

# Register http://admin.localhost -> http://127.0.0.1:8080 and get JSON confirmation
toolkit proxy add admin 8080 --json
```

***

### toolkit proxy remove

Unregister a `*.localhost` route by its subdomain name. After removal, the subdomain will no longer resolve through the toolkit proxy daemon.

**Syntax**

```bash theme={null}
toolkit proxy remove <subdomain> [options]
```

**Arguments**

| Argument      | Type     | Required | Description                                                                         |
| :------------ | :------- | :------- | :---------------------------------------------------------------------------------- |
| `<subdomain>` | `string` | Yes      | The subdomain to unregister (e.g., `api` removes the `http://api.localhost` route). |

**Options**

| Option   | Type      | Default | Description                             |
| :------- | :-------- | :------ | :-------------------------------------- |
| `--json` | `boolean` | `false` | Emit the result of the removal as JSON. |

**Examples**

```bash theme={null}
# Remove the proxy route for http://api.localhost
toolkit proxy remove api

# Remove http://admin.localhost and receive a JSON confirmation
toolkit proxy remove admin --json
```