Skip to main content

gws expose

Manage expose sessions for services.

Usage​

gws expose add <service> [worktree]  [options]
gws expose remove <service> [worktree] 
gws expose list [worktree] [options]

Output:

# Starting expose session
🔌 Starting expose session for service: api
   Worktree: feature-auth
   Namespace: myapp-feature-auth

✨ Expose session started successfully!
   Service: api
   Local: localhost:54321
   Remote: myapp-feature-auth:9229

💡 Test connection: curl http://localhost:54321
💡 View status: gws status
💡 Stop expose: gws expose remove api

Note: This command can be run from anywhere using the -p [project] option.

Arguments​

  • <action> - Action: add, remove, or list. Required.
  • [service] - Name of the service to expose (required for add/remove)
  • [worktree] - Worktree name (optional, defaults to current worktree)

Options​

OptionDescriptionDefault
-p, --project <name>Project nameAuto-detected from current directory
--local-port <port>Local port to bind (auto-allocated if not specified)Auto-allocated
--remote-port <port>Remote port in container (defaults to service.port)Service port
--jsonOutput as JSON (for list action)false

Examples:

# Expose api service (default worktree)
gws expose add api

# Expose api in feature-auth worktree
gws expose add api feature-auth

# Expose with specific local port
gws expose add api --local-port 8080

# Expose with specific remote port
gws expose add api --remote-port 9229

# List active expose sessions
gws expose list

# List for specific worktree
gws expose list feature-auth

# List as JSON
gws expose list --json

# Stop expose session
gws expose remove api

# Stop expose for specific worktree
gws expose remove api feature-auth

Typical Use Cases​

Debug Node.js application​

# 1. Expose debugger port
gws expose add api feature-auth --remote-port 9229

# Output shows allocated port (e.g., localhost:54321)

# 2. Attach VS Code debugger
# In VS Code launch.json:
# {
#   "type": "node",
#   "request": "attach",
#   "name": "Attach to Remote",
#   "address": "localhost",
#   "port": 54321
# }

Connect to database​

# Expose database port with specific local port
gws expose add database feature-auth --remote-port 5432 --local-port 5433

# Connect with psql
psql -h localhost -p 5433 -U postgres -d myapp

Access Redis CLI​

# Expose Redis port
gws expose add redis feature-auth --remote-port 6379

# Connect with redis-cli (use allocated port from output)
redis-cli -h localhost -p <allocated-port>

Monitor application metrics​

# Expose Prometheus metrics
gws expose add api feature-auth --remote-port 9090 --local-port 9090

# Access metrics
curl http://localhost:9090/metrics

Multirepo Behavior​

When running gws expose in a multirepo setup, the command targets a specific service within the shared namespace.

Project Structure​

myapp/                          # Parent directory
├── .worktrees/                 # Shared worktrees folder (at parent level)
│   └── feature-auth/           # One folder per worktree name
│       ├── api/                # Worktree for api repo
│       │   └── src/
│       └── app/                # Worktree for app repo
│           └── src/
├── api/                        # Git repo 1
│   ├── .git/
│   └── src/
└── app/                        # Git repo 2
    ├── .git/
    └── src/

Exposing Service in Main Workspace​

cd myapp
gws expose add api --remote-port 9229

Output:

🔌 Starting expose session for service: api
   Worktree: myapp
   Namespace: myapp

✨ Expose session started successfully!
   Service: api
   Local: localhost:54321
   Remote: myapp:9229

What happens:

  • Finds the api service pod in namespace myapp
  • Creates port-forward from localhost:54321 to api container port 9229
  • Expose session persists in the background

Exposing Service in Worktree​

cd myapp
gws expose add database feature-auth --remote-port 5432 --local-port 5433

Output:

🔌 Starting expose session for service: database
   Worktree: feature-auth
   Namespace: myapp-feature-auth

✨ Expose session started successfully!
   Service: database
   Local: localhost:5433
   Remote: myapp-feature-auth:5432

What happens:

  • Finds the database service pod in namespace myapp-feature-auth
  • Creates port-forward from localhost:5433 to database container port 5432
  • You can now connect to the database at localhost:5433

Listing Active Exposes​

gws expose list

Output:

🔌 Active Expose Sessions (3):

  Namespace: myapp
    ✅ api: localhost:54321 → 9229
       Status: running

  Namespace: myapp-feature-auth
    ✅ api: localhost:54322 → 9229
       Status: running
    ✅ database: localhost:5433 → 5432
       Status: running

Key Points:

  • All services from all repos are in the same namespace
  • You can expose different services from different worktrees simultaneously
  • Each expose session gets its own unique local port
  • Use gws expose list to see all active port-forwards
  • Expose sessions persist until you stop the worktree with gws down or manually remove with gws expose remove

Understanding expose​

The expose command creates a port-forward from your local machine to a container. It:

  1. Identifies the pod for the service
  2. Establishes a port-forward tunnel
  3. Binds the local port to the container port
  4. Keeps the connection active in the background

The port-forward runs as a background process and persists until you stop the worktree with gws down or manually remove the expose session.

Port Conflicts​

If you get a "port already in use" error:

  1. Choose a different local port with --local-port
  2. Stop the process using the port
  3. Use gws down to clean up existing port-forwards

See Also​