> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel-labs/portless/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with Portless in under 2 minutes

# Quickstart

Get Portless up and running in under 2 minutes.

## Installation

<Steps>
  <Step title="Install Portless globally">
    Install via npm:

    ```bash theme={null}
    npm install -g portless
    ```

    <Info>
      Portless requires Node.js 20+ and works on macOS and Linux.
    </Info>
  </Step>

  <Step title="Run your first app">
    Navigate to any project and run your dev server through Portless:

    ```bash theme={null}
    portless run next dev
    ```

    Or specify a name explicitly:

    ```bash theme={null}
    portless myapp next dev
    ```

    The proxy will auto-start if needed, and your app will be available at:

    ```
    http://myapp.localhost:1355
    ```

    <Tip>
      The name is automatically inferred from your `package.json`, git repo, or directory name when you use `portless run`.
    </Tip>
  </Step>

  <Step title="Access your app">
    Open your browser and visit:

    ```
    http://myapp.localhost:1355
    ```

    That's it! Your app is now running with a stable, human-readable URL.
  </Step>
</Steps>

## First Commands

### Run with Auto-Inferred Name

Portless automatically infers your project name from `package.json`, git repo, or directory:

```bash theme={null}
portless run next dev
# -> http://<project>.localhost:1355
```

### Run with Explicit Name

Specify the name directly:

```bash theme={null}
portless myapp next dev
# -> http://myapp.localhost:1355
```

### Use Subdomains

Organize related services under the same domain:

```bash theme={null}
portless api.myapp pnpm start
# -> http://api.myapp.localhost:1355

portless docs.myapp npm run dev
# -> http://docs.myapp.localhost:1355
```

### Add to package.json

Make Portless the default for your project:

```json package.json theme={null}
{
  "scripts": {
    "dev": "portless run next dev"
  }
}
```

Now anyone on your team can just run `npm run dev` and get a stable URL.

<Info>
  The proxy auto-starts when you run an app. You can also start it explicitly with `portless proxy start`.
</Info>

## Working Example

Let's say you're building a full-stack app with a Next.js frontend and an Express API.

<Steps>
  <Step title="Start the API">
    ```bash theme={null}
    cd api
    portless api.myapp node server.js
    ```

    Your API is now running at `http://api.myapp.localhost:1355`.
  </Step>

  <Step title="Start the frontend">
    ```bash theme={null}
    cd frontend
    portless myapp next dev
    ```

    Your frontend is now running at `http://myapp.localhost:1355`.
  </Step>

  <Step title="Configure the frontend to call the API">
    Update your frontend to call the API by its stable URL:

    ```typescript app/api/route.ts theme={null}
    export async function GET() {
      const response = await fetch('http://api.myapp.localhost:1355/data');
      const data = await response.json();
      return Response.json(data);
    }
    ```

    No more hardcoded port numbers. The URL stays the same even if the underlying port changes.
  </Step>
</Steps>

## Git Worktree Support

If you use git worktrees, Portless automatically detects them and prepends the branch name as a subdomain:

```bash theme={null}
# Main worktree (main/master branch)
portless run next dev
# -> http://myapp.localhost:1355

# Linked worktree on branch "fix-ui"
portless run next dev
# -> http://fix-ui.myapp.localhost:1355

# Linked worktree on branch "feature/auth"
portless run next dev
# -> http://auth.myapp.localhost:1355
```

This means you can put `portless run` in your `package.json` once and it just works everywhere - the main checkout uses the plain name, and each worktree gets a unique subdomain. No `--force` needed, no name collisions.

<Tip>
  You can disable Portless temporarily by setting `PORTLESS=0` or `PORTLESS=skip` when running commands.
</Tip>

## Managing the Proxy

The proxy starts automatically when you run an app, but you can also control it manually:

<CodeGroup>
  ```bash Start theme={null}
  portless proxy start
  ```

  ```bash Stop theme={null}
  portless proxy stop
  ```

  ```bash List Routes theme={null}
  portless list
  ```

  ```bash Start with HTTPS theme={null}
  portless proxy start --https
  ```
</CodeGroup>

## Environment Variables Injected

When you run an app through Portless, these environment variables are automatically injected:

| Variable       | Description                        | Example                       |
| -------------- | ---------------------------------- | ----------------------------- |
| `PORT`         | The port your app should listen on | `4123`                        |
| `HOST`         | The host your app should bind to   | `127.0.0.1`                   |
| `PORTLESS_URL` | The public URL to access your app  | `http://myapp.localhost:1355` |

Most frameworks automatically respect `PORT` and `HOST`. For frameworks that don't, Portless auto-injects the correct flags.

## Static Aliases (Advanced)

If you have a service running outside of Portless (like a Docker container), you can register it manually:

```bash theme={null}
portless alias db 5432
# -> http://db.localhost:1355 routes to localhost:5432
```

To remove an alias:

```bash theme={null}
portless alias --remove db
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Why Portless?" icon="lightbulb" href="/why">
    Learn about the problems Portless solves and real-world use cases
  </Card>

  <Card title="Environment Variables" icon="gear" href="/environment-variables">
    Configure Portless with environment variables and advanced options
  </Card>
</CardGroup>

<Warning>
  If you're using Safari and `.localhost` URLs don't resolve, run `sudo portless hosts sync`. Safari relies on the system DNS resolver which may not handle `.localhost` subdomains on all configurations.
</Warning>