# Expose

> Expose is a tunnel application that allows you to share your local sites and applications with others on the internet and receive webhooks during development. It's open source, written in PHP, and the best ngrok alternative for PHP developers.

## Quick Start

Install via Laravel Herd (pre-installed), PHAR download, or Composer:
```bash
composer global require exposedev/expose
```

Set your token:
```bash
expose token YOUR_TOKEN
```

Share a site:
```bash
expose share my-site.test
```

## Documentation

### Client

- [Installation](/docs/getting-started/installation): Install via Laravel Herd, PHAR, or Composer. Update with `expose self-update`.

- [Authentication](/docs/getting-started/authentication): Get a token at expose.dev/register. Configure with `expose token YOUR_TOKEN`. Free plan uses random subdomains with time limits; Pro gets custom subdomains and no limits.

- [Sharing Sites](/docs/client/sharing): Use `expose` in project directory (assumes `foldername.test`) or `expose share URL` explicitly. Supports HTTP and HTTPS local sites.

- [Custom Subdomains](/docs/client/sharing#share-a-local-site-with-specific-subdomain) (Pro): Use `--subdomain=name` to specify subdomain. Useful for webhooks where you need consistent URLs.

- [Dashboard](/docs/client/dashboard): Web dashboard at localhost:4040 shows all HTTP requests in realtime. Click requests to inspect headers, body, response. Replay requests without re-triggering webhooks.

- [Password Protection](/docs/client/basic-authentication): Add basic auth with `--basicAuth="user:pass"`. Can't layer on sites already using basic auth.

- [Catch-All](/docs/client/catch-all): `expose catch-all` gives you a URL that always returns 200 and logs all requests to the dashboard. Useful for inspecting webhooks without local endpoint.

### Expose Network (Pro Features)

- [Global Servers](/docs/expose-network/global-server-infrastructure): Servers in EU, US (2), Asia Pacific, India, South America, Australia. Use `expose servers` to list. Set default with `expose default-server REGION`.

- [Reserved Subdomains](/docs/expose-network/reserved-subdomains): Reserve subdomains on sharedwithexpose.com so others can't take them.

- [Custom Domains](/docs/expose-network/custom-domains): Add your own domain via CNAME. Use `--domain=share.yourdomain.com`. Set default with `expose default-domain`.

- [Teams](/docs/expose-network/teams): Share reserved subdomains and custom domains with team members.

### Advanced Usage

- [Site Configuration (expose.yaml)](/docs/advanced-usage/expose-yaml): Per-project config file for local-url, subdomain, custom-domain, expose-server, auth credentials. Shared with team via version control.

- [Request Plugins](/docs/advanced-usage/request-plugins): Highlight webhook events in CLI/dashboard. Built-in plugins for GitHub, Paddle Billing. Create custom plugins with `expose make:plugin`.

### Self-Hosted Server

For full control, host your own Expose server. Clone the [GitHub repo](https://github.com/exposedev/server).

- [Starting the Server](/docs/server/server/starting-the-server): `expose-server serve domain.com --port=8080`. Use `--validateAuthTokens` to require auth. Use supervisord to keep running.

- [SSL Support](/docs/server/server/ssl): Use Nginx, Apache, HAProxy, or Caddy as reverse proxy for HTTPS. Configure websocket support.

- [Admin Interface](/docs/server/server/admin-interface): Available at http://expose.your-domain.com. Protected with basic auth. Manage users, view shared sites, configure server settings.

- [Server Configuration](/docs/server/server/server-configuration): Enable auth token validation, set message of the day, maximum connection length, custom error messages.

### Extending the Server

- [Subdomain Generator](/docs/server/extending-the-server/subdomain-generator): Implement `SubdomainGenerator` interface to customize random subdomain generation.

- [User Repository](/docs/server/extending-the-server/user-repository): Implement `UserRepository` interface to load users from custom storage instead of SQLite.

- [Custom Views](/docs/server/extending-the-server/custom-views): Modify `resources/views/homepage.blade.php` and `resources/views/errors/404.blade.php`.

## CLI Commands Reference

```
expose                           # Share current directory as foldername.test
expose info                      # Show current config (token, server, domain, plan, version, latency)
expose share URL                 # Share specific URL
expose share URL --subdomain=X   # Share with custom subdomain (Pro)
expose share URL --server=eu-1   # Share via specific server (Pro)
expose share URL --domain=X      # Share via custom domain (Pro)
expose share URL --basicAuth="user:pass"  # Add password protection
expose catch-all                 # Create catch-all endpoint for webhook testing
expose token TOKEN               # Set authentication token
expose servers                   # List available servers
expose default-server REGION     # Set default server
expose default-domain DOMAIN     # Set default custom domain
expose default-domain:clear      # Clear default domain
expose plugins                   # List request plugins
expose plugins:manage            # Enable/disable plugins
expose make:plugin               # Create custom request plugin
expose self-update               # Update Expose client
```