hass-web-proxy-lib

What it is and what it does

hass-web-proxy-lib is a small library for Home Assistant integration developers that abstracts the mechanics of proxying web traffic (HTTP and WebSocket) through Home Assistant's built-in web server. Rather than being an integration itself, it provides reusable base classes—ProxyView for HTTP proxying and WebsocketProxyView for WebSocket proxying—that integration developers inherit from and customize by implementing a single method, _get_proxied_url(), to determine where each request should be routed.

The library handles the plumbing of receiving requests at a Home Assistant API endpoint, validating authentication, forwarding traffic to a target URL, and returning responses. It includes exception classes for common HTTP error conditions (400, 401, 403, 404, 410) that integrations can raise to signal errors, a ProxiedURL dataclass to configure per-request behavior, and test utilities (fixtures and handlers) to help integration developers write tests for their proxy implementations.

Use it for:

• Build a Home Assistant integration that exposes a local device's web interface through Home Assistant without exposing the device directly to the internet.
• Create a custom integration that proxies API calls to a backend service, applying Home Assistant authentication and authorization rules.
• Test a Home Assistant integration's proxy logic using the provided local_server fixture and response handlers.
• Implement WebSocket proxying for integrations that need to relay real-time data streams through Home Assistant.
• Develop an integration that conditionally routes requests based on config entry data without writing HTTP server boilerplate.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides base classes and utilities for Home Assistant integrations to proxy HTTP and WebSocket traffic through Home Assistant's web server.

Yes, if you are developing a Home Assistant integration that needs to proxy traffic. The library eliminates boilerplate for a common pattern, has no external dependencies, carries permissive licensing, and is actively maintained. Install only if you are building a custom Home Assistant integration; it is not useful as a standalone package.

Install

hass-web-proxy-lib on PyPI

pip install hass-web-proxy-lib

uv add hass-web-proxy-lib

poetry add hass-web-proxy-lib

Installing hass-web-proxy-lib

Before you install

Low install friction with no runtime dependencies. Active maintenance with recent releases; last commit on 2026-08-03 and latest release on 2026-05-05 indicate ongoing support.

License in practice

MIT license permits use in proprietary and open-source projects with minimal restrictions; attribution required.

Quickstart

from hass_web_proxy_lib import ProxyView, ProxiedURL

class MyProxyView(ProxyView):
    url = "/api/my_integration/proxy/"
    name = "api:my_integration:proxy"
    
    def _get_proxied_url(self, request):
        return ProxiedURL(url="https://target.example.com/path")

Requires Python >=3.14.2,<4.0; integration must be used within a Home Assistant environment with access to hass.http and async_get_clientsession().

Verify before relying

• Whether the library supports HTTP methods beyond GET (PUT, POST, DELETE, PATCH) in ProxyView or only in WebsocketProxyView.
• Performance characteristics and limits for concurrent proxy requests or large payloads.
• Whether authentication/authorization logic can be customized beyond the allow_unauthenticated flag in ProxiedURL.

Package facts

Evidence: hass_web_proxy_lib-0.0.8-py3-none-any.whl

Tags

More Home Automation packages