API Reference

This page contains the complete API documentation for Hostify.

Host Class

class hostify.Host(domain, port=None, path=None, api_token=None)[source]

Bases: object

Main class for hosting applications via Cloudflare Tunnels.

Simple one-line API:: Host(domain=”app.example.com”, port=3000).serve()
Or with static files:: Host(domain=”app.example.com”, path=”./public”).serve()

__init__(domain, port=None, path=None, api_token=None)[source]

Initialize Host instance.

Parameters:

domain (str) – Full domain or subdomain (e.g., “app.example.com”)
port (Optional[int]) – Port of existing local server (mutually exclusive with path)
path (Optional[str]) – Path to static files to serve (mutually exclusive with port)
api_token (Optional[str]) – Cloudflare API token (optional, reads from CF_API_TOKEN env var)

Raises:

HostError – If configuration is invalid

cleanup()[source]

Clean up all resources.

This method: 1. Stops cloudflared process 2. Deletes DNS record 3. Deletes tunnel 4. Stops static server if running

Return type:: None

serve()[source]

Start hosting the application.

This method: 1. Validates the local server or starts static server 2. Creates Cloudflare tunnel 3. Creates DNS record 4. Starts cloudflared process 5. Monitors and keeps alive

Raises:: HostError – If setup fails
Return type:: None

The Host class is the main entry point for using Hostify. It manages the entire lifecycle of hosting your application through Cloudflare Tunnels.

Constructor Parameters

class Host(domain, port=None, path=None, api_token=None)

Initialize a Host instance.

Parameters:

domain (str) – Full domain or subdomain (e.g., “app.example.com”). Required.
port (int) – Port number where your application is running (1-65535). Mutually exclusive with path.
path (str) – Path to directory containing static files to serve. Mutually exclusive with port.
api_token (str) – Cloudflare API token. If not provided, reads from CF_API_TOKEN environment variable.

Raises:

HostError – If configuration is invalid (e.g., both port and path specified, or neither specified).

Note

You must specify either port OR path, but not both.

Methods

serve()

Start hosting the application.

This method:

Validates the local server or starts static server
Creates Cloudflare tunnel
Creates DNS record
Starts cloudflared process
Monitors and keeps the connection alive

Raises:: HostError – If setup fails at any step.
Returns:: None (blocks until Ctrl+C is pressed)

Example:

from hostify import Host

host = Host(domain="app.example.com", port=3000)
host.serve()  # Blocks until Ctrl+C

cleanup()

Clean up all resources.

This method is called automatically when you press Ctrl+C or when the program exits. It:

Stops cloudflared process
Deletes DNS record
Deletes tunnel
Stops static server if running

You typically don’t need to call this manually.

Returns:: None

Exceptions

Cloudflare Module

class hostify.cloudflare.Cloudflare(api_token=None)[source]

Bases: object

Cloudflare API client for managing tunnels and DNS records.

Requires CF_API_TOKEN or CLOUDFLARE_API_TOKEN environment variable with permissions: - Account → Cloudflare Tunnel → Edit - Zone → DNS → Edit - Zone → Read

BASE_URL = 'https://api.cloudflare.com/client/v4'

__init__(api_token=None)[source]

Initialize Cloudflare API client.

Parameters:: api_token (Optional[str]) – Cloudflare API token. If None, reads from CF_API_TOKEN or CLOUDFLARE_API_TOKEN env var.
Raises:: CloudflareAPIError – If API token is not provided.

configure_tunnel_route(tunnel_id, hostname, service)[source]

Configure a route for a tunnel (public hostname).

Parameters:

tunnel_id (str) – Tunnel ID
hostname (str) – Hostname to route (e.g., “app.example.com”)
service (str) – Service URL (e.g., “http://localhost:8000”)

Return type:

Dict

Returns:

Route configuration dict

create_dns_record(zone_id, subdomain, tunnel_id)[source]

Create a CNAME DNS record pointing to a tunnel.

Parameters:

zone_id (str) – Zone ID
subdomain (str) – Full subdomain (e.g., “app.example.com”)
tunnel_id (str) – Tunnel ID

Return type:

str

Returns:

DNS record ID

create_tunnel(name)[source]

Create a new Cloudflare Tunnel.

Parameters:: name (str) – Tunnel name
Return type:: Tuple[str, Dict]
Returns:: Tuple of (tunnel_id, credentials_dict)

delete_dns_record(zone_id, record_id)[source]

Delete a DNS record.

Parameters:

zone_id (str) – Zone ID
record_id (str) – DNS record ID

Return type:

None

delete_tunnel(tunnel_id, force=False)[source]

Delete a Cloudflare Tunnel.

Parameters:

tunnel_id (str) – Tunnel ID to delete
force (bool) – If True, attempts to clean up connections before deleting

Return type:

None

find_existing_record(zone_id, subdomain)[source]

Find existing DNS record for a subdomain.

Parameters:

zone_id (str) – Zone ID
subdomain (str) – Subdomain to search for

Return type:

Optional[Dict]

Returns:

DNS record dict if found, None otherwise

get_account_id()[source]

Get the first available account ID.

Return type:: str
Returns:: Account ID string.
Raises:: CloudflareAPIError – If no accounts found.

get_accounts()[source]

Get all Cloudflare accounts.

Return type:: List[Dict]
Returns:: List of account dictionaries.

get_headers()[source]

Get authentication headers for API requests.

Return type:: Dict[str, str]
Returns:: Dictionary with Authorization header.

get_zone_id(domain)[source]

Get zone ID for a domain.

Parameters:: domain (str) – Domain name (e.g., “example.com”)
Return type:: str
Returns:: Zone ID string.
Raises:: CloudflareAPIError – If zone not found.

list_dns_records(zone_id, record_type=None)[source]

List DNS records for a zone.

Parameters:

zone_id (str) – Zone ID
record_type (Optional[str]) – Optional filter by record type (A, CNAME, etc.)

Return type:

List[Dict]

Returns:

List of DNS record dictionaries.

list_tunnels()[source]

List all tunnels for the account.

Return type:: List[Dict]
Returns:: List of tunnel dictionaries.

save_credentials(tunnel_id, credentials)[source]

Save tunnel credentials to local file.

Parameters:

tunnel_id (str) – Tunnel ID
credentials (Dict) – Credentials dictionary

Return type:

str

Returns:

Path to saved credentials file

class hostify.cloudflare.CloudflareAPIError[source]

Bases: Exception

Custom exception for Cloudflare API errors.

Cloudflared Module

class hostify.cloudflared.Cloudflared[source]

Bases: object

Manager for cloudflared binary and tunnel processes.

Handles: - OS detection - Binary download and caching - Tunnel process management - Log capture

DOWNLOAD_URLS = {'darwin': 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-amd64', 'linux': 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64', 'windows': 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe'}

__init__()[source]: Initialize cloudflared manager.

get_binary_path()[source]

Get path to cloudflared binary, downloading if necessary.

Return type:: str
Returns:: Path to cloudflared binary
Raises:: CloudflaredError – If download or setup fails

get_logs(lines=50)[source]

Get recent log output from tunnel process.

Parameters:: lines (int) – Number of lines to retrieve
Return type:: str
Returns:: Log output string

is_running()[source]

Check if tunnel process is running.

Return type:: bool
Returns:: True if running, False otherwise

run_tunnel(tunnel_id, credentials_path, port, host='localhost')[source]

Start cloudflared tunnel process.

Parameters:

tunnel_id (str) – Tunnel ID
credentials_path (str) – Path to credentials JSON file
port (int) – Local port to tunnel
host (str) – Local host (default: localhost)

Return type:

Popen

Returns:

Popen process object

Raises:

CloudflaredError – If tunnel fails to start

stop_tunnel()[source]

Stop the running tunnel process.

Return type:: None

class hostify.cloudflared.CloudflaredError[source]

Bases: Exception

Custom exception for cloudflared errors.

Utility Functions

Utility functions for hostify.

hostify.utils.ensure_dir(path)[source]

Ensure a directory exists, creating it if necessary.

Parameters:: path (str) – Directory path
Return type:: None

hostify.utils.get_home_dir()[source]

Get user’s home directory.

Return type:: str
Returns:: Path to home directory

hostify.utils.is_port_in_use(port, host='127.0.0.1')[source]

Check if a port is in use by trying to connect to it.

Parameters:

port (int) – Port number to check
host (str) – Host to check (default: localhost)

Return type:

bool

Returns:

True if port is in use (server is listening), False otherwise

hostify.utils.start_static_server(path, port)[source]

Start a simple HTTP server for static files.

Parameters:

path (str) – Path to directory to serve
port (int) – Port to serve on

Return type:

Popen

Returns:

Popen process object

hostify.utils.validate_server(port, host='127.0.0.1')[source]

Validate that a server is running on the specified port.

Parameters:

port (int) – Port number to check
host (str) – Host to check (default: localhost)

Return type:

bool

Returns:

True if server is accessible, False otherwise

Type Hints

All functions and methods in Hostify include type hints for better IDE support and type checking.

Example with type hints:

from hostify import Host
from typing import Optional

def create_host(
    domain: str,
    port: Optional[int] = None,
    path: Optional[str] = None
) -> Host:
    return Host(domain=domain, port=port, path=path)

host = create_host("app.example.com", port=3000)
host.serve()