Prime Tunnel

What is Prime Tunnel?

Prime Tunnel creates secure, public URLs for services running on your local machine. You start a local server, create a tunnel, and get an HTTPS URL that anyone can access. Common use cases:

Expose a local development server to the internet
Receive webhooks from external services during development
Share a work-in-progress app with teammates

Hosted evaluations can use Prime Tunnel too. Launch the run with --allow-tunnel-access, then create the tunnel from inside the hosted sandbox using the same API or CLI flow described here. The flag only grants tunnel permissions to the temporary PRIME_API_KEY. See Hosted Evaluations.

Complete Example

Here’s a full working example: start a local HTTP server and expose it to the internet. 1. Start a local server

# Create a simple HTML file
echo '<h1>Hello from Prime Tunnel!</h1>' > index.html

# Start Python's built-in HTTP server on port 8000
python -m http.server 8000

2. Create a tunnel (in another terminal)

import asyncio
from prime_tunnel import Tunnel

async def main():
    tunnel = Tunnel(local_port=8000)
    await tunnel.start()

    print(f"Public URL: {tunnel.url}")
    print("Press Ctrl+C to stop")

    # Keep running until interrupted
    try:
        while True:
            await asyncio.sleep(1)
    except KeyboardInterrupt:
        pass
    finally:
        await tunnel.stop()

asyncio.run(main())

prime tunnel start --port 8000

3. Access your server Open the printed URL (e.g., https://t-0-abc123def456.tunnel.pinfra.io) in any browser. Your local server is now accessible from anywhere.

Context Manager

For automatic cleanup, use the async context manager:

async with Tunnel(local_port=8000) as tunnel:
    print(f"URL: {tunnel.url}")
    # Tunnel is active here
# Tunnel automatically stopped

Tunnel Properties

tunnel = Tunnel(local_port=8000)
await tunnel.start()

tunnel.tunnel_id  # "t-0-abc123def456"
tunnel.url        # "https://t-0-abc123def456.tunnel.pinfra.io"

Protecting a Tunnel with Basic Auth

By default, anyone with the URL can reach your tunnel. To require credentials, provide a username when creating the tunnel — a strong password is auto-generated server-side and shown exactly once. All public traffic must then include HTTP basic auth; requests without valid credentials get a 401 Unauthorized.

tunnel = Tunnel(local_port=8000, http_user="alice")
await tunnel.start()

print(tunnel.url)
print(tunnel.http_password)  # auto-generated

prime tunnel start --port 8000 --auth alice

The CLI prints the generated password when the tunnel starts:

Tunnel started successfully!
URL: https://t-0-abc123def456.tunnel.pinfra.io
Tunnel ID: t-0-abc123def456
Basic auth user: alice
Basic auth password: vBI6ioyAM3_X4KWaEug4TPSbzovK8eYb
Save this password - it is shown only once and cannot be retrieved later

Browsers prompt for the credentials automatically. For programmatic access, send the Authorization header:

curl -u alice:vBI6ioyAM3_X4KWaEug4TPSbzovK8eYb https://t-0-abc123def456.tunnel.pinfra.io

CLI Commands

# Start a tunnel
prime tunnel start --port 8000

# Start a tunnel protected by HTTP basic auth (password is auto-generated)
prime tunnel start --port 8000 --auth alice

# List active tunnels
prime tunnel list

# Stop a tunnel
prime tunnel stop t-0-abc123def456

Rate Limits

The tunnel API enforces per-user rate limits over a 60-second window.

Endpoint	Method	Limit
`/api/v1/tunnel`	`POST`	600 requests / 60s
`/api/v1/tunnel`	`GET`	300 requests / 60s
`/api/v1/tunnel/{id}`	`GET`	300 requests / 60s per tunnel
`/api/v1/tunnel/{id}`	`DELETE`	100 requests / 60s
`/api/v1/tunnel`	`DELETE`	100 requests / 60s (bulk)

Requests over the limit return 429 Too Many Requests. There is also a per-account cap on the number of concurrent tunnels (tunnel_limit on the wallet) - delete unused tunnels before creating new ones.

Getting Started

Lab

Libraries

Compute

prime-rl

prime-rl

prime-rl

prime-rl

prime-rl

prime-rl

prime-rl

prime-rl

prime-rl

prime-rl

prime-rl

prime-rl

prime-rl

What is Prime Tunnel?

Complete Example

Context Manager

Tunnel Properties

Protecting a Tunnel with Basic Auth

CLI Commands

Rate Limits

​What is Prime Tunnel?

​Complete Example

​Context Manager

​Tunnel Properties

​Protecting a Tunnel with Basic Auth

​CLI Commands

​Rate Limits

What is Prime Tunnel?

Complete Example

Context Manager

Tunnel Properties

Protecting a Tunnel with Basic Auth

CLI Commands

Rate Limits