Parallel Works
View as Markdown
Share:

pw endpoints run

pw endpoints run

Run a command that serves HTTP and expose it as an endpoint

Synopsis

Spawn a command that serves HTTP on a local port and forward it through an endpoint, tearing the whole process tree down when this command exits.

The CLI assigns a free local port; reference it in your command with the port token, or read it from the PORT environment variable. Reference the endpoint's public hostname with the host token (also exported as PW_ENDPOINT_HOST) to give a dev server the public host it must allow-list. Reference the base path the endpoint is served under with the path token (also exported as PW_ENDPOINT_PATH): "/me/session/<you>/<name>/" for a path-based endpoint (--no-subdomain) or "/" for a subdomain one. Set an app's base path to it so its links resolve behind the prefix, such as Jupyter's --ServerApp.base_url. The full public URL is exported as PW_ENDPOINT_URL.

pw endpoints run -- COMMAND [ARGS...] [flags]

Examples

  pw endpoints run -- jupyter lab --port {port} --no-browser --ServerApp.allow_remote_access=True
  
  # Same, on a path-based endpoint: {path} sets Jupyter's base URL to the session prefix
  pw endpoints run --no-subdomain --name jupyter -- jupyter lab --port {port} --no-browser --ServerApp.allow_remote_access=True --ServerApp.base_url={path}
  
  # Run a node server that reads $PORT
  pw endpoints run --name api -- node server.js
  
  # Serve an Ollama model (--rewrite-host satisfies its host guard; sh -c sets its OLLAMA_HOST bind var)
  pw endpoints run --rewrite-host -- sh -c 'OLLAMA_HOST=127.0.0.1:{port} ollama serve'
  
  # Serve a model with llama.cpp (llama-server takes --port directly)
  pw endpoints run -- llama-server -hf ggml-org/gpt-oss-20b-GGUF --port {port}
  
  # Give an app its public host so it accepts requests through the endpoint
  pw endpoints run -- my-dev-server --allowed-host {host}
  
  # Pin the local port
  pw endpoints run --port 5173 -- npm run dev

Options

      --description string                  Session description (defaults to "Endpoint on <hostname>")
  -h, --help                                help for run
      --keep                                Keep the endpoint session on exit instead of deleting it
  -n, --name string                         Name for the endpoint session (defaults to a server-generated name)
      --no-subdomain                        Skip subdomain assignment and use the path-based session URL
      --open                                Open the endpoint URL in the browser
      --openai                              Expose this endpoint as an OpenAI-compatible model in the platform chat and AI providers. Point it at a local /v1 server (vLLM, Ollama, etc.); pass --auth-file if that server needs an API key.
  -o, --output string                       Output format (interactive, text); interactive shows a live dashboard and downgrades to text when stdout is not a terminal (default "interactive")
  -p, --port int                            Local port to assign the command (default: a free port chosen automatically)
      --public                              Make the endpoint publicly accessible: anyone with the link can reach it without logging in. Requires your organization to allow public sessions.
      --rewrite-host string[="localhost"]   Rewrite the Host header sent to your local app to this value (defaults to "localhost" when the flag is given without one). Use for an app that rejects the public endpoint host, such as a DNS-rebinding guard or an allowed-hosts check.
      --slug string                         Session base-path slug (default "/")
      --strip-path                          Strip the session URL prefix before forwarding to your app (use only if your app serves at the root path and can't be configured with a base path; by default the full path is forwarded so set your app's base path to the endpoint URL)
  -s, --subdomain string                    Serve at this subdomain: a label (my-app), which lands on the platform's default sessions domain, or the full host under any registered sessions domain (my-app.<sessions domain>); a random subdomain is used by default when the platform supports them

Options inherited from parent commands

      --context string         The context to use. Overrides PW_CONTEXT environment variable and current context from config.
      --platform-host string   The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
  -v, --verbose                Enable verbose logging

SEE ALSO

  • pw endpoints - Create and serve self-registering endpoint sessions