Download the PHP package getxpos/laravel without Composer

XPOS for Laravel

Instant public URLs for Laravel development. Expose your local app with a single command or programmatically from code — supports token auth, reserved subdomains, custom domains, and TCP tunnels.

xpos.dev

Features

• One Command — php artisan xpos gets you a public HTTPS URL instantly
• Programmatic API — Xpos::connect(['port' => 8000]) for webhook testing and automated workflows
• TCP Tunnels — expose databases, Redis, or any TCP service
• Token Auth — longer sessions, reserved subdomains, and custom domains with an XPOS token
• Reserved Subdomains — keep myapp.xpos.to across sessions (Pro plan)
• Custom Domains — use your own domain like dev.example.com (Business plan)
• Auto-Start Server — starts php artisan serve automatically if not running
• Auto TrustProxies — HTTPS URLs work correctly out of the box
• Laravel 10+ — full support

Installation

Quick Start

CLI:

Programmatic:

Authentication

For longer sessions and more features, add your XPOS token to .env:

Get your token at xpos.dev/dashboard/tokens.

CLI Usage

Programmatic API

Create tunnels from your PHP code — useful for webhook testing, integration tests, and automated workflows.

Basic Usage

With Options

Without Facade

Webhook Testing

Callbacks

Note: onClose fires during wait() or close() — PHP runs synchronously, so there is no background event loop.

TCP Tunnels

Expose any TCP service (databases, Redis, message queues, etc.).

CLI

Programmatic

Note: TCP tunnels require authentication (a token). The tunnel URL is an ip:port pair instead of an HTTPS URL.

Configuration

Publish the config file:

Options in config/xpos.php:

HTTPS & TrustProxies

The package automatically configures Laravel's TrustProxies middleware so asset(), url(), route(), and other helpers generate correct HTTPS URLs when accessed through an XPOS tunnel.

This works with *.xpos.to subdomains, custom domains, and any future tunnel domains. Disable with XPOS_TRUST_PROXIES=false in .env if needed.

Requirements

• PHP 8.1+
• Laravel 10+
• SSH client in PATH

Security

The auth token is written to a per-process SSH config file (mode 0600, inside a private 0700 temp directory) as the User directive, and the SDK spawns ssh -F <config> xpos — so the token is not placed on the ssh command line and does not appear in ps, /proc/<pid>/cmdline, or shell history. The config file is removed when the tunnel exits.

To minimize exposure:

• Set XPOS_TOKEN in .env rather than passing --token=tk_xxx on the command line — passing it as an artisan argument would surface it in shell history / the artisan process's argv. .env keeps it out of shell history, source control, and CI logs.
• Rotate tokens regularly and revoke any token you suspect was exposed — manage tokens at xpos.dev/dashboard/tokens.
• Avoid running on shared multi-user hosts where untrusted local users can inspect process state.

Residual exposure: the token lives in that 0600 temp config file for the tunnel's lifetime, and — when supplied via XPOS_TOKEN — in this process's environment (/proc/<pid>/environ, readable only by the same UID or root) — both far tighter than the ps-readable argv of older designs.

Troubleshooting

Port already in use?

SSH connection issues?

• Ensure SSH client is installed and in PATH
• Check firewall settings for port 443

HTTPS URLs not working?

• Ensure trust_proxies is true in config/xpos.php
• Clear config cache: php artisan config:clear

Reserved subdomain not working?

• Ensure XPOS_TOKEN is set in .env
• Verify your plan supports reserved subdomains at xpos.dev

TCP mode requires --port?

• TCP mode doesn't auto-start artisan serve — you must specify the port of the service you're exposing: --mode=tcp --port=5432

TCP tunnel shows "authentication required"?

• TCP tunnels require a token. Set XPOS_TOKEN in .env or pass --token=tk_xxx

.gitignore

Add .xpos.pid to your project's .gitignore:

Links

• Website: xpos.dev
• Dashboard: xpos.dev/dashboard
• GitHub: github.com/getxpos/laravel

License

MIT License. See LICENSE for details.