portless

KO | EN

gitlite — search

#typescript #golang #rust #deep-learning #linux #macos #nodejs #java #awesome #cli #awesome-list #pytorch #security #ios

(★ 11,195)

포트 번호를 안정적인 이름 기반 로컬 URL로 대체하세요. 사람과 에이전트 모두를 위해.

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
  - release.yml
- pre-commit
- - next.config.mjs
  - package.json
  - postcss.config.mjs
  - tsconfig.json
  - vitest.config.ts
- - .env.example
  - .gitignore
  - components.json
  - next.config.ts
  - package.json
  - postcss.config.mjs
  - README.md
  - tsconfig.json
- - .gitignore
  - .npmignore
  - package.json
  - tsconfig.json
  - tsup.config.ts
- - provision.sh
  - run.sh
  - start.sh
  - stop.sh
  - sync.sh
- - SKILL.md
- - SKILL.md
- - .gitignore
  - package.json
  - requirements.txt
  - tsconfig.json
  - vitest.config.ts
.gitignore
.node-version
.prettierignore
.prettierrc
AGENTS.md
CHANGELOG.md
eslint.config.js
LICENSE
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
turbo.json

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# portless
로컬 개발 시 포트 번호를 안정적이고 이름이 지정된 `.localhost` URL로 대체합니다. 개발자와 에이전트를 위한 도구입니다.
```diff
- "dev": "next dev" # http://localhost:3000
+ "dev": "portless run next dev" # https://myapp.localhost
```
## 설치
\*\*전역 설치 (권장):\*\*
```bash
npm install -g portless
```
\*\*또는 프로젝트 개발 의존성으로 설치:\*\*
```bash
npm install -D portless
```
> portless는 1.0 이전 버전입니다. 프로젝트별로 설치하는 경우, 기여자마다 서로 다른 버전을 실행할 수 있습니다. 릴리스 간에 상태 디렉터리 형식이 변경될 수 있으며, 이 경우 `portless trust`를 다시 실행해야 할 수 있습니다.
## 앱 실행
```bash
portless myapp next dev
# -> https://myapp.localhost
```
기본적으로 HTTP/2를 지원하는 HTTPS가 활성화됩니다. 첫 실행 시 portless는 로컬 CA를 생성하고 신뢰하도록 설정한 뒤 443번 포트에 바인딩합니다 (macOS/Linux에서는 sudo를 통해 자동으로 권한이 상승됩니다). 일반 HTTP를 사용하려면 `--no-tls`를 사용하세요.
앱을 실행하면 프록시가 자동으로 시작됩니다. `PORT` 환경 변수를 통해 임시 포트(4000-4999)가 할당됩니다. 대부분의 프레임워크(Next.js, Express, Nuxt 등)는 이를 자동으로 인식합니다. `PORT`를 무시하는 프레임워크(Vite, VitePlus, Astro, React Router, Angular, Expo, React Native)의 경우, portless가 올바른 `--port` 플래그와 필요한 경우 일치하는 `--host` 플래그를 자동으로 주입합니다. 플래그 주입은 프레임워크 이름이나 알려진 러너로 시작하는 패키지 스크립트 명령어(`"dev": "vite"`, `"dev": "bunx vite"`)를 통해 이루어집니다. 프레임워크의 서버 명령어(`dev`, `serve`, `preview`, `start`, 단독 `vite`, 또는 `vite [root]`)에만 플래그가 적용되며, `vite build`, `vite optimize`, `vp test`, `astro check`와 같이 서버를 실행하지 않는 명령어는 플래그를 거부하고 그대로 유지됩니다. Expo 연결 모드(`--localhost`, `--lan`, `--tunnel`)는 유지되면서 할당된 포트만 주입됩니다. portless가 분류할 수 없는 스크립트 역시 그대로 유지됩니다: 추적하지 않는 플래그 문법을 가진 CLI의 하위 명령어 앞에 있는 플래그(`vp --mode dev build`) 등이 이에 해당합니다. 또한 portless는 플래그를 추가하는 것이 정상적으로 작동하지 않는 스크립트도 그대로 둡니다: 복합 명령어(`&&`, `|`, `;`), 후행 `#` 주석, 자체 `--` 옵션 터미네이터, 환경 변수 접두사(`NODE\_ENV=production vite`), 다른 스크립트로의 위임(`"dev": "npm run dev:vite"`), 스크립트 이름 앞의 러너 플래그(`bun run --bun dev`) 등이 그렇습니다. 이 경우 자체 포트를 유지하므로 스크립트 내에서 직접 설정해야 합니다.
자동 시작 시 portless는 가장 최근 프록시 실행의 설정(포트, TLS, TLD)을 재사용하므로, 재시작이나 재부팅 후에도 조용히 기본값으로 돌아가지 않습니다. 명시적 환경 변수(`PORTLESS\_PORT`, `PORTLESS\_HTTPS` 등)가 항상 우선합니다.
Portless는 사용자별 상태를 `~/.portless`에 저장합니다. sudo 권한으로 프록시가 실행될 때, 프록시와 권한이 없는 앱 프로세스가 동일한 라우트 등록 정보를 공유할 수 있도록 호출한 사용자의 홈 디렉터리에서 이 경로를 확인합니다.
비대호형 환경(TTY가 없거나 `CI=1`인 경우)에서는 프롬프트 창을 띄우는 대신 설명과 함께 에러를 출력하며 종료되므로, turborepo나 CI 스크립트 같은 작업 러너들이 명확한 메시지와 함께 조기에 실패하도록 합니다.
## 설정
기본 `portless` 명령어는 별도의 설정 없이 바로 작동합니다. 패키지 이름, git 루트 또는 디렉터리에서 앱 이름을 추론하여 `package.json`의 `"dev"` 스크립트를 프록시를 통해 실행합니다.
```bash
portless # -> "dev" 스크립트를 실행, https://.localhost
```
기본값을 재정의하려면 선택적으로 `portless.json`을 사용하세요:
```json
{ "name": "myapp" }
```
```bash
portless # -> "dev" 스크립트를 실행, https://myapp.localhost
```
스크립트는 기본적으로 `"dev"`를 사용합니다. 설정에 이름이 지정되지 않은 경우 `package.json`에서 이름을 유추합니다.
### 모노레포
레포지토리 루트에 있는 하나의 `portless.json`이 모든 워크스페이스 패키지를 커버합니다. Portless는 `pnpm-workspace.yaml` 또는 `package.json`의 `"workspaces"` 필드(npm, yarn, bun)에서 패키지를 감지합니다:
```json
{
"apps": {
"apps/web": { "name": "myapp" },
"apps/api": { "name": "api.myapp" }
}
}
```
```bash
portless # 레포지토리 루트에서 실행: "dev" 스크립트를 가진 모든 워크스페이스 패키지 시작
cd apps/web && portless # 단일 패키지만 시작
```
`apps` 맵은 선택 사항이며 이름 재정의가 필요한 경우에만 사용됩니다. 나열되지 않은 패키지도 계속 자동 감지됩니다

`package.json`에서 이름을 유추합니다.

`apps` 맵이 없는 경우, 호스트 이름은 `..localhost` 규칙을 따릅니다. 프로젝트 이름은 워크스페이스 패키지 전체에서 가장 흔한 npm 스코프(예: `@myorg/web` 및 `@myorg/api`는 `myorg`를 생성)에서 가져오며, 폴백으로 워크스페이스 루트 디렉터리 이름을 사용합니다. 패키지의 단축 이름이 프로젝트 이름과 일치하는 경우, 중복 없이 기본 `.localhost`를 갖게 됩니다.

### 설정 필드

| 필드 | 타입 | 기본값 | 설명 |
| --------- | ------- | -------- | --------------------------------------------------------- |
| `name` | string | 유추됨 | 기본 앱 이름. 워크트리 접두사가 여전히 적용됩니다. |
| `script` | string | `"dev"` | 실행할 `package.json` 스크립트의 이름입니다. |
| `appPort` | number | 자동 | 하위 프로세스를 위한 고정 포트입니다. |
| `proxy` | boolean | 자동 | 프록시를 통해 라우팅할지 여부입니다. 자동 감지됩니다. |
| `apps` | object | | 워크스페이스 패키지에 대한 오버라이드이며, 상대 경로를 키로 사용합니다. |
| `turbo` | boolean | `true` | turborepo 대신 직접 생성(spawning)을 사용하려면 `false`로 설정합니다. |

### package.json의 "portless" 키

별도의 `portless.json` 대신 `package.json`에 `"portless"` 키를 추가할 수 있습니다. 문자열 값은 이름을 설정하는 단축키입니다:

```json
{
  "name": "@myorg/web",
  "portless": "myapp"
}
```

객체는 모든 앱별 필드(`name`, `script`, `appPort`, `proxy`)를 지원합니다:

```json
{
  "name": "@myorg/web",
  "portless": { "name": "myapp", "script": "dev:app" }
}
```

`package.json`의 `"portless"` 키는 `portless.json` 앱 항목보다 우선하지만, CLI 플래그에 의해 오버라이드됩니다.

### --script 플래그

단일 실행에 대해 기본 스크립트를 오버라이드합니다:

```bash
portless --script start # "dev" 대신 "start" 실행
portless --script test # "dev" 대신 "test" 실행
```

### Turborepo

turborepo와 함께 portless를 사용하려면, `dev` 스크립트로 `portless`를 지정하고 실제 명령은 별도의 스크립트에 넣으세요:

```json
{
  "scripts": {
    "dev": "portless",
    "dev:app": "next dev"
  },
  "portless": { "name": "myapp", "script": "dev:app" }
}
```

Turbo는 portless를 호출하는 각 패키지의 `dev` 스크립트를 실행합니다. Portless는 설정을 읽고, 패키지 매니저를 감지한 다음, 프록시를 통해 `pnpm run dev:app`(또는 yarn/bun/npm)을 실행합니다. `turbo.json`을 변경할 필요가 없습니다.

루트에서의 `pnpm dev`는 평소처럼 turbo를 통해 작동합니다. portless가 없는 사람들도 `pnpm run dev:app`을 직접 실행할 수 있습니다.

## package.json에서 사용

`package.json` 스크립트에서 여전히 portless를 사용할 수 있습니다:

```json
{
  "scripts": {
    "dev": "portless run next dev"
  }
}
```

`portless.json`을 사용하면 다음과 같이 단순화할 수 있습니다:

```json
{
  "scripts": {
    "dev": "next dev"
  }
}
```

그런 다음 `portless` 또는 `portless run`을 실행하여 프록시를 거치게 합니다.

## 서브도메인

서브도메인으로 서비스를 구성하세요:

```bash
portless api.myapp pnpm start
# -> https://api.myapp.localhost
portless docs.myapp next dev
# -> https://docs.myapp.localhost
```

기본적으로 명시적으로 등록된 서브도메인만 라우팅됩니다(엄격 모드). 등록된 라우트의 모든 서브도메인이 해당 앱으로 폴백되도록 하려면(예: 추가 등록 없이 `tenant1.myapp.localhost`가 `myapp` 앱으로 라우팅됨) 프록시를 시작할 때 `--wildcard`를 사용하세요.

## Git 워크트리

`portless run`은 git 워크트리를 자동으로 감지합니다. 연결된 워크트리에서는 브랜치 이름이 서브도메인으로 앞에 추가되므로, 설정 변경 없이 각 워크트리가 고유한 URL을 갖게 됩니다:

```bash
# 메인 워크트리 (접두사 없음)
portless run next dev # -> https://myapp.localhost
# "fix-ui" 브랜치의 연결된 워크트리
portless run next dev # -> https://fix-ui.myapp.localhost
```

워크트리 접두사를 유지하면서 유추된 기본 이름을 오버라이드하려면 `--name`을 사용하세요:

```bash
portless run --name myapp next dev # -> https://fix-ui.myapp.localhost
```

`package.json`에 `portless run`을 한 번만 넣어두면 어디서든 작동합니다. 메인 체크아웃은 일반 이름을 사용하고, 각 워크트리는 고유한 서브도메인을 얻습니다. 충돌도 없고 `--force`도 필요 없습니다.

## 커스텀 TLD

기본적으로 portless는 대부분의 브라우저에서 `127.0.0.1`로 자동 확인되는 `.localhost`를 사용합니다. 다른 TLD(예: `.test`)를 선호하는 경우 `--tld`를 사용하세요:

```bash
portle
```

ss proxy start --tld test
portless myapp next dev
# -> https://myapp.test
```
프락시는 라우트 호스트 이름(`.test` 포함)을 위해 `/etc/hosts`를 자동으로 동기화하므로, 해당 도메인들은 내 컴퓨터에서 정상적으로 해결됩니다.
하나의 프락시에서 여러 TLD를 사용하여 동일한 앱 이름에 접근하려면 `--tld`를 반복해서 사용하세요:
```bash
portless proxy start --tld localhost --tld test
portless myapp next dev
# -> https://myapp.localhost
# -> https://myapp.test
```
여러 TLD가 설정된 경우, `PORTLESS\_URL`은 첫 번째 TLD를 사용합니다. `PORTLESS\_TLD`는 쉼표로 구분된 목록(예: `PORTLESS\_TLD=localhost,test`)도 지원합니다.
권장 사항: `.test` (IANA 예약됨, 충돌 위험 없음). `.local`(mDNS/Bonjour와 충돌) 및 `.dev`(Google 소유, HSTS를 통해 HTTPS 강제)는 피하세요.

### 멀티 세그먼트 TLD
`--tld` 값으로는 소문자 DNS 이름(점으로 구분된 하나 이상의 레이블, 후행 점 없음)을 사용할 수 있으므로, 사용 중인 도메인을 "TLD"로 사용할 수 있습니다. 이를 통해 로컬 URL이 프로덕션과 동일한 구조를 가지게 되어, 양쪽 환경 모두에서 OAuth 리디렉션 URI, 서브도메인 간 쿠키, 호스트 기반 라우팅이 동일하게 작동합니다:
```bash
portless proxy start --tld dev.example.com
portless myapp next dev
# -> https://myapp.dev.example.com
```
각 레이블은 DNS 규칙을 따라야 합니다. 소문자, 숫자, 내부 하이픈을 사용해야 하며, 레이블당 최대 63자, 전체 총합 253자까지 허용됩니다. 전체 호스트 이름(`app.TLD`) 역시 253자 DNS 제한을 받습니다.
프락시는 등록된 호스트 이름을 위해 `/etc/hosts`를 자동으로 동기화하므로, `myapp.dev.example.com`은 내 컴퓨터에서 `127.0.0.1`로 해결됩니다. 이는 루프백 전용 설정입니다. LAN 모드가 아닐 때 프락시는 `127.0.0.1` 및 `::1`에만 바인딩되므로(아래 참조), 사용자 정의 TLD는 프락시를 실행 중인 컴퓨터에서만 접근할 수 있습니다. 다른 기기에서 프락시에 접근하려면 LAN 모드(`--lan`)가 필요하지만, LAN 모드는 `.local` TLD로 앱을 제공하고 사용자 정의 `--tld`를 무시하므로 현재 두 기능을 함께 사용할 수는 없습니다.
엄격한 OAuth 제공업체(Google, Apple)는 `.localhost` 및 `.test` 리디렉션 URI를 거부하지만 실제 도메인은 허용하므로, `https://myapp.dev.example.com/api/auth/callback/google`은 리디렉션 URI로 정상 작동합니다.

## 작동 방식
```mermaid
flowchart TD
Browser["Browser  
myapp.localhost"]
Proxy["portless proxy  
(port 80 or 443)"]
App1[":4123  
myapp"]
App2[":4567  
api"]
Browser --> Proxy
Proxy --> App1
Proxy --> App2
```

1. \*\*프락시 시작\*\*: 앱을 실행할 때 자동으로 시작되거나, `portless proxy start`로 명시적으로 시작할 수 있습니다.
2. \*\*앱 실행\*\*: `portless  `는 빈 포트를 할당하고 프락시에 등록합니다.
3. \*\*URL을 통한 접근\*\*: `https://.localhost`는 프락시를 거쳐 앱으로 라우팅됩니다.

LAN 모드가 아닐 경우, 프락시와 HTTP 리디렉션 리스너는 IPv4 및 IPv6 루프백 주소인 `127.0.0.1`과 `::1`에만 바인딩됩니다. LAN, VPN 또는 기타 네트워크 인터페이스를 통한 연결은 허용하지 않습니다.

## HTTP/2 + HTTPS
HTTP/2를 지원하는 HTTPS가 기본적으로 활성화되어 있습니다. 브라우저는 호스트당 HTTP/1.1 연결을 6개로 제한하므로, 번들링되지 않은 많은 파일을 제공하는 개발 서버(Vite, Nuxt 등)에서는 병목 현상이 발생합니다. HTTP/2는 단일 연결을 통해 모든 요청을 다중화(multiplexing)합니다.
WebSocket은 두 프로토콜 버전 모두에서 작동하므로, 개발 서버의 HMR(Next.js, Vite 등)이 프락시를 통해 정상 작동합니다. HTTP/1.1 `Upgrade` 요청은 그대로 전달되며, HTTP/2 연결을 통해 열린 WebSocket은 확장된 CONNECT(RFC 8441)를 사용합니다.
처음 실행 시 portless는 로컬 CA를 생성하여 시스템 신뢰 저장소에 추가합니다. 브라우저 경고나 수동 설정이 필요 없습니다.
```bash
# 나만의 인증서 사용 (예: mkcert에서 생성한 인증서)
portless proxy start --cert ./cert.pem --key ./key.pem
# HTTPS 비활성화 (포트 80에서 일반 HTTP 사용)
portless proxy start --no-tls
# 첫 실행 시 신뢰 프롬프트를 건너뛴 경우, 나중에 CA 신뢰 설정
portless trust
```
Linux에서 `portless trust`는 Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, openSUSE를 지원합니다(`update-ca-certificates` 또는 `update-ca-trust` 사용). Windows에서는 `certutil`을 사용하여 시스템 신뢰 저장소에 CA를 추가합니다. WSL에서는 Linux 신뢰 저장소와 Windows 현재 사용자 Root 저장소를 모두 업데이트하여 Windows 브라우저가 portl

HTTPS 인증서를 발급합니다.
## OS 시작 시 실행
터미널에서 프록시를 시작하지 않고도 재부팅 후 깔끔한 HTTPS URL을 사용할 수 있도록 프록시를 OS 시작 서비스로 설치합니다:
```bash
portless service install
portless service install --lan
portless service install --wildcard
PORTLESS\_STATE\_DIR=~/.portless-lan PORTLESS\_LAN=1 portless service install
portless service status
portless service uninstall
```
이 서비스는 설치 옵션이나 `PORTLESS\_*` 환경 변수가 제공되지 않는 한 기본값(포트 443의 HTTPS 및 `.localhost` 이름)을 사용합니다. `service install`은 `--port`, `--no-tls`, `--lan`, `--ip`, `--tld`, `--wildcard`, `--cert`, `--key`를 포함하여 `proxy start`에 사용할 수 있는 프록시 옵션을 허용합니다. 서비스 상태와 로그가 기록될 위치를 지정하려면 `--state-dir` 또는 `PORTLESS\_STATE\_DIR=`을 사용하세요.
선택한 서비스 설정은 launchd, systemd 또는 작업 스케줄러(Task Scheduler)에 기록되며 재부팅 후에도 재사용됩니다. `portless service status`는 설치된 포트, HTTPS 모드, TLD, LAN 모드, 와일드카드 모드 및 상태 디렉토리를 보고합니다. macOS와 Linux는 부팅 시 포트 443에 바인딩할 수 있도록 root 소유의 서비스를 설치합니다. Windows는 SYSTEM으로 실행되는 작업 스케줄러 시작 작업을 설치합니다. 설치 및 제거 시 관리자 권한이 필요할 수 있습니다. `portless clean`은 서비스를 자동으로 제거합니다.
## LAN 모드
```bash
portless proxy start --lan
portless proxy start --lan --https
portless proxy start --lan --ip 192.168.1.42
```
`--lan`은 프록시를 IPv4 및 IPv6 미지정 주소인 `0.0.0.0`과 `::`에 명시적으로 바인딩하고 mDNS 검색으로 전환합니다. 이를 통해 동일한 네트워크의 기기에서 서비스를 `.local`로 사용할 수 있습니다. Portless는 LAN IP를 자동으로 감지하고 Wi-Fi/IP 변경을 자동으로 따르지만, `--ip`를 사용하거나 `PORTLESS\_LAN\_IP`를 내보내어(export) 다른 주소를 고정할 수 있습니다. 프록시가 시작될 때마다 LAN 모드가 기본값이 되도록 하려면 셸에 `PORTLESS\_LAN=1`을 설정하세요(0/1 부울).
Portless는 `proxy.lan`을 통해 LAN 모드를 기억하므로 LAN 프록시를 중지했다가 다시 시작해도 LAN 모드가 유지됩니다. 모든 프록시 설정(포트, TLS, TLD, LAN)은 명시적 플래그나 환경 변수로 재정의되지 않는 한 자동 시작 시 유지되고 재사용됩니다. `.localhost` 모드로 다시 전환하려면 일시적으로 시작할 때 `PORTLESS\_LAN=0`을 사용하세요. 다른 명시적 LAN/TLS/TLD 설정으로 프록시가 이미 실행 중인 경우, Portless는 경고를 표시하고 먼저 중지하도록 요청합니다.
LAN 모드는 Portless가 이미 생성하는 시스템 mDNS 도구에 의존합니다. macOS는 `dns-sd`를 기본 탑재하고 있으며, Linux는 `avahi-utils`의 `avahi-publish-address`를 사용합니다(`sudo apt install avahi-utils` 또는 배포판에 해당하는 명령어로 설치). 명령어가 누락되었거나 네트워크에 연결할 수 없는 경우, `portless proxy start --lan`은 관련 오류를 출력하고 종료됩니다.
### 프레임워크 참고 사항
- \*\*Next.js\*\*: `.local` 호스트명을 `allowedDevOrigins`에 추가하세요:
```js
// next.config.js
module.exports = {
allowedDevOrigins: ["myapp.local", "\*.myapp.local"],
};
```
- \*\*Expo / React Native\*\*: Portless는 항상 `--port`를 주입합니다. React Native에는 `--host 127.0.0.1`도 지정됩니다. Expo는 LAN 모드 외에서는 `--host localhost`를 사용하지만, LAN 모드에서는 `--host`나 `HOST`를 강제하는 대신 Metro가 기본 LAN 호스트 동작을 따르도록 둡니다.
## Tailscale 공유
[Tailscale](https://tailscale.com) 네트워크의 팀원들과 개발 서버를 공유하세요:
```bash
portless myapp --tailscale next dev
# -> https://myapp.localhost (local)
# -> https://devbox.yourteam.ts.net (tailnet)
```
각 `--tailscale` 앱은 자체 Tailscale HTTPS 포트에 루트 마운트되므로 프레임워크의 `basePath` 설정이 필요 없습니다. 첫 번째 앱에는 포트 443이 할당되고, 이후 앱에는 8443, 8444 등이 할당됩니다.
```bash
portless myapp --tailscale next dev # -> https://devbox.ts.net
portless api --tailscale pnpm start # -> https://devbox.ts.net:8443
```
[Tailscale Funnel](https://tailscale.com/kb/1223/funnel/)을 통해 퍼블릭 인터넷에 개발 서버를 노출하려면 `--funnel`을 사용하세요:
```bash
portless myapp --funnel next dev
# -> https://devbox.yourteam.ts.net (public)
```
Tailscale HTTPS 인증서

ates는 `--tailscale` 또는 `--funnel`이 HTTPS URL을 등록하기 전에 활성화되어 있어야 합니다. `--funnel`이 공인 URL을 등록하려면 tailnet 및 노드에서도 Funnel이 활성화되어 있어야 합니다. 두 설정 중 하나라도 누락되면 portless는 자식 프로세스를 시작하기 전에 종료됩니다.
모든 앱을 기본적으로 공유하려면 셸 프로필이나 `.env`에 `PORTLESS\_TAILSCALE=1`을 설정하세요. `portless list`는 로컬 및 tailnet URL을 모두 보여줍니다. Tailscale serve 등록은 앱이 종료될 때 자동으로 정리됩니다.
Tailscale CLI가 설치되어 있고 연결되어 있어야 하며(`tailscale up`), Tailscale HTTPS 인증서가 활성화되어 있어야 합니다.
## ngrok 공유
[ngrok](https://ngrok.com)을 사용하여 개발 서버를 공인 인터넷에 노출하세요:
```bash
portless myapp --ngrok next dev
# -> https://myapp.localhost (local)
# -> https://abc123.ngrok.app (public)
```
portless가 앱을 실행할 때 기본적으로 ngrok을 활성화하려면 셸 프로필이나 `.env`에 `PORTLESS\_NGROK=1`을 설정하세요. `portless list`는 로컬 및 ngrok URL을 모두 보여줍니다. ngrok 터널은 앱이 종료될 때 자동으로 정리됩니다.
ngrok CLI가 설치되어 있고 인증되어 있어야 합니다. ngrok이 인증 오류를 보고하면 `ngrok config add-authtoken `을 실행하고 다시 시도하세요.
## 명령어
```bash
portless # Run dev script through proxy
portless # From monorepo root: run all workspace packages
portless run [--name ] [cmd] [args...] # Infer name, run through proxy
portless   [args...] # Run app at https://.localhost
portless alias   # Register a static route (e.g. for Docker)
portless alias   --force # Overwrite an existing route
portless alias --remove  # Remove a static route
portless list # Show active routes
portless doctor # Check proxy, routes, DNS, and CA trust
portless trust # Add local CA to system trust store
portless clean # Remove state, CA trust entry, and hosts block
portless prune # Kill orphaned dev servers from crashed sessions
portless hosts sync # Add routes to /etc/hosts (fixes Safari)
portless hosts clean # Remove portless entries from /etc/hosts
# Disable portless (run command directly)
PORTLESS=0 pnpm dev # Bypasses proxy, uses default port
# Proxy control
portless proxy start # Start the HTTPS proxy (port 443, daemon)
portless proxy start --no-tls # Start without HTTPS (port 80)
portless proxy start --lan # Start in LAN mode (mDNS .local for devices)
portless proxy start -p 1355 # Start on a custom port (no sudo)
portless proxy start --foreground # Start in foreground (for debugging)
portless proxy start --wildcard # Allow unregistered subdomains to fall back to parent
portless proxy stop # Stop the proxy
# OS startup service
portless service install # Start HTTPS proxy when the OS starts
portless service install --lan # Start service in LAN mode
portless service install --wildcard # Persist wildcard routing in the service
portless service status # Show service and proxy status
portless service uninstall # Remove the startup service
```
### 옵션
```
-p, --port  Port for the proxy (default: 443, or 80 with --no-tls)
--no-tls Disable HTTPS (use plain HTTP on port 80)
--https Enable HTTPS (default, accepted for compatibility)
--lan Enable LAN mode (mDNS .local for real devices)
--ip  Pin a specific LAN IP (disables auto-follow; use with --lan)
--cert  Use a custom TLS certificate
--key  Use a custom TLS private key
--foreground Run proxy in foreground instead of daemon
--tld  Use a custom TLD instead of .localhost; repeat for more
--wildcard Allow unregistered subdomains to fall back to parent route
--state-dir  Use a custom state directory with service install
--script  Run a specific package.json script (default: dev)
--app-port  Use a fixed port for the app (skip auto-assignment)
--tailscale Share the app on your Tailscale network (tailnet)
--funnel Share the app publicly via Tailscale Funnel
--ngrok Share the app publicly via ngrok
--force Kill the existing process and take over its route
--name  Use  as the app name
```
### 환경 변수
```
# Configuration
PORTLESS\_PORT= Override the default proxy

port
PORTLESS\_APP\_PORT= 앱에 고정 포트 사용 (--app-port와 동일)
PORTLESS\_HTTPS=0 HTTPS 비활성화 (--no-tls와 동일)
PORTLESS\_LAN=1 1로 설정 시 LAN 모드 활성화 (LAN IP 자동 감지)
PORTLESS\_LAN\_IP= LAN 모드에서 사용할 특정 LAN IP 고정
PORTLESS\_TLD=[,] 하나 이상의 TLD 사용 (예: localhost,test)
PORTLESS\_WILDCARD=1 등록되지 않은 서브도메인이 부모 라우트로 폴백되도록 허용
PORTLESS\_SYNC\_HOSTS=0 /etc/hosts 자동 동기화 비활성화 (기본값: 활성화)
PORTLESS\_TAILSCALE=1 Tailscale 네트워크에서 앱 공유 (--tailscale과 동일)
PORTLESS\_FUNNEL=1 Tailscale Funnel을 통해 공개적으로 앱 공유 (--funnel과 동일)
PORTLESS\_NGROK=1 ngrok을 통해 공개적으로 앱 공유 (--ngrok과 동일)
PORTLESS\_STATE\_DIR= 상태 디렉토리 오버라이드
# 자식 프로세스에 주입됨
PORT 자식 프로세스가 수신 대기해야 하는 임시 포트
HOST 보통 127.0.0.1 (LAN 모드의 Expo에서는 생략됨)
PORTLESS\_URL 주요 공개 URL (예: https://myapp.localhost)
PORTLESS\_TAILSCALE\_URL 앱의 Tailscale URL (--tailscale이 활성화된 경우)
PORTLESS\_NGROK\_URL 앱의 ngrok URL (--ngrok이 활성화된 경우)
NODE\_EXTRA\_CA\_CERTS portless CA의 경로 (HTTPS가 활성화된 경우)
```
> \*\*예약된 이름:\*\* `run`, `get`, `alias`, `hosts`, `list`, `doctor`, `trust`, `clean`, `prune`, `proxy`, `service`는 서브 명령어이므로 앱 이름으로 직접 사용할 수 없습니다. 프로젝트에서 이름을 유추하려면 `portless run `을 사용하고, 예약된 이름을 포함하여 어떤 이름이든 강제로 지정하려면 `portless --name  `을 사용하세요.
## 제거 / 초기화
내부 머신에서 portless 데이터를 제거하려면 (`~/.portless` 및 시스템 상태 디렉토리의 프록시 상태, portless가 설치한 경우 OS 신뢰 저장소의 로컬 CA, `/etc/hosts`의 portless 블록):
```bash
portless clean
```
macOS/Linux에서는 `sudo` 입력을 요구할 수 있습니다. `--cert` 및 `--key`로 전달된 커스텀 인증서 경로는 삭제되지 않습니다. 신뢰 저장소 제거에 실패하면, 나중에 `portless clean`을 통해 안전하게 다시 시도할 수 있도록 portless가 CA 인증서와 키를 유지합니다.
## Safari / DNS
Chrome, Firefox, Edge에서는 `.localhost` 서브도메인이 `127.0.0.1`로 자동 해결됩니다. Safari는 시스템 DNS 리졸버에 의존하므로, 일부 구성에서는 `.localhost` 서브도메인을 처리하지 못할 수 있습니다.
Safari에서 `.localhost` URL을 찾지 못하는 경우:
```bash
portless hosts sync # 현재 라우트를 /etc/hosts에 추가
portless hosts clean # 나중에 정리
```
기본적으로 라우트 호스트명(`.localhost`, 커스텀 TLD, LAN `.local`)에 대해 `/etc/hosts`를 자동 동기화합니다. 비활성화하려면 `PORTLESS\_SYNC\_HOSTS=0`을 설정하세요.
## 문제 해결
상태를 변경하지 않고 로컬 상태를 검사하려면 `portless doctor`를 실행하세요. Node.js, 상태 디렉토리, 프록시 활성 상태, 라우트 항목, HTTPS CA 신뢰, 호스트명 해결, LAN 모드 사전 요구 사항을 확인한 후 수정 제안 사항을 출력합니다.
## Portless 앱 간 프록시
프론트엔드 개발 서버(예: Vite, webpack)가 다른 portless 앱으로 API 요청을 프록시하는 경우, 프록시가 `Host` 헤더를 재작성(rewrite)하는지 확인하세요. 그렇지 않으면 portless가 요청을 프론트엔드로 다시 라우팅하여 무한 루프에 빠지게 됩니다.
\*\*Vite\*\* (`vite.config.ts`):
```ts
server: {
proxy: {
"/api": {
target: "https://api.myapp.localhost",
changeOrigin: true,
ws: true,
},
},
}
```
\*\*webpack-dev-server\*\* (`webpack.config.js`):
```js
devServer: {
proxy: [{
context: ["/api"],
target: "https://api.myapp.localhost",
changeOrigin: true,
}],
}
```
Portless는 Node.js가 portless CA를 신뢰할 수 있도록 자식 프로세스에 `NODE\_EXTRA\_CA\_CERTS`를 자동으로 설정합니다. portless 외부에서 별도의 Node.js 프로세스를 실행하는 경우, CA를 수동으로 지정하세요: `NODE\_EXTRA\_CA\_CERTS=~/.portless/ca.pem`. 또는 일반 HTTP를 사용하려면 `--no-tls`를 사용하세요.
Portless는 이 잘못된 구성을 감지하여 이 수정 방법을 안내하는 메시지와 함께 `508 Loop Detected`로 응답합니다.
## 개발
이 저장소는 [Turborepo](https://turbo.build)를 사용하는 pnpm 워크스페이스 모노레포입니다. 배포 가능한 패키지는 `packages/portless/`에 위치합니다.
저장소 개발을 위해서는 Node.js 24+ 및 pnpm 11을 사용하세요. `.node-version` 파일은 버전 관리자를 위한 Node 메이저 버전을 고정합니다.
```bash
pnpm install # 모든 종속성 설치

ncies
pnpm build # 모든 패키지 빌드
pnpm test # 테스트 실행
pnpm test:coverage # 커버리지와 함께 테스트 실행
pnpm lint # 모든 패키지 린트 실행
pnpm type-check # 모든 패키지 타입 검사
pnpm format # Prettier로 모든 파일 포맷팅
```
## 요구 사항
- Node.js 24+
- macOS, Linux, 또는 Windows
- Tailscale CLI (`--tailscale` 및 `--funnel`용, 선택 사항)
- ngrok CLI (`--ngrok`용, 선택 사항)

portless

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

portless

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README