---
id: hass-web-proxy-lib
version: "0.0.8"
license: MIT
license_treatment: permissive
maintenance: active
---

# hass-web-proxy-lib — A library to proxy web traffic through Home Assistant integrations.

License: permissive · Maintenance: active · Downloads: 606.7K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: capped_below_current
- Install friction: low
- Maintenance: active
- Downloads: 606.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

home assistant proxy library, http proxy home assistant, websocket proxy integration, home assistant web traffic routing, custom integration proxy utilities, home-assistant, integration-framework

[View on SkillFed](https://skillfed.io/packages/hass-web-proxy-lib) · [View on PyPI](https://pypi.org/project/hass-web-proxy-lib/)