SparkTunnel & downloads

Help me prepare my existing project for PhotonSpark Webhost using the guide below. Ask for the project requirements and deployment choice when missing. Inspect existing files before editing, preserve behavior and data, and do not invent supported flags or deployment options. Keep credentials out of code and prompts. Explain dashboard settings and test production behavior. Publishing, DNS changes, and destructive actions need my authorization. Report what passed and what remains unverified.

# SparkTunnel & downloads

Publish a service running on your computer, a Docker host, or a private network through a public HTTPS hostname.

Source: https://webhost.photonspark.com/docs/sparktunnel

## Choose the correct connector

SparkTunnel keeps your application on your machine. Webhost provides the public hostname and HTTPS edge; the connector forwards requests to the locally approved target. Your application still needs its own login if access should be restricted.

- SparkTunnel 0.4 preview uses WireGuard over native UDP, with two independent gateway paths. It uses an enrollment grant and explicit activation.
- Legacy connectors use outbound HTTPS/WebSocket and a connector token. Keep an existing legacy token with a legacy download.
- The 0.4 preview is unsigned and does not update itself. Preview availability is not stable-release certification. Download only an operating-system build actually listed below.
- 0.4 has no automatic TCP/HTTPS or legacy fallback. Outbound UDP must work on the connector's network.

## Download a published build

The catalog below comes from Webhost's public download API. Version, operating system, artifact type, and verification files are shown for the builds currently published. Downloads do not require sign-in.

- [Preview catalog (JSON)](https://webhost.photonspark.com/api/v1/client-apps/spark-tunnel-preview)
- [Legacy catalog (JSON)](https://webhost.photonspark.com/api/v1/client-apps)

## Set up SparkTunnel 0.4

For a deliberately selected LAN or Docker-network target, review the destination and use --allow-lan when required. localhost inside a container refers to that container, not the Docker host or a different service. An example such as http://nginx:8080 only works where that name and port are reachable.

Native credential storage must be available for a saved profile. Headless Linux has an explicit protected-file credential-store option; inspect the CLI help before choosing it. Never paste enrollment grants or saved credentials into Git, docs, or an AI prompt.

1. Verify the local application responds from the same machine or container network where the connector will run.
2. Sign in to Webhost, open the Site's SparkTunnel panel, and obtain a one-time 0.4 enrollment grant. Do not recreate an existing working tunnel merely to download a client.
3. Download the published CLI or desktop build for your OS. The desktop asks for the grant inside the app. For the CLI, use the example below and paste the grant only at the hidden prompt.
4. Approve the exact local target. Wait for current configuration and healthy paths, then use Activate SparkTunnel 0.4 in the dashboard when available.
5. Verify Public transport is SparkTunnel 0.4, the status is Online, and the public application behaves correctly. Enrollment alone does not switch live traffic.

```sh
chmod +x ./DOWNLOADED_CLI
./DOWNLOADED_CLI run --server https://webhost.photonspark.com --enroll --target http://127.0.0.1:3000
# On later starts, reuse the enrolled profile:
./DOWNLOADED_CLI run --profile default
```

## Run a legacy connector

Create or open a legacy SparkTunnel Site, configure the local target, and use its connector token with a legacy CLI. Store the token privately. The live catalog lists the supported operating systems and builds.

On Windows PowerShell, invoke the downloaded executable with .\filename.exe and keep the command on one line. For an unattended process, use the OS service manager and a protected credential setup; do not expose credentials in a shared unit file or log.

```sh
chmod +x ./spark-tunnel-linux-amd64
# Substitute your private connector token locally, never in shared instructions.
./spark-tunnel-linux-amd64 run --server https://webhost.photonspark.com --token 'YOUR_PRIVATE_CONNECTOR_TOKEN' --target http://127.0.0.1:3000
```

## Understand the status

- Connections A and B are two paths to the same approved service. They are not two copies of your application.
- Origin reachable describes connectivity. The application can still return a legitimate 401 or 404.
- Ready for activation checks means setup is eligible for the next checks; it does not mean public traffic has switched.
- Status unavailable means the dashboard cannot establish fresh status. Check connectivity, refresh, and clock synchronization before assuming the tunnel is absent.
- Failover can restore new connections. Existing uploads, WebSockets, or requests are not promised transparent replay or resumption.
- Revoking a device removes its authority. Do not use revocation or tunnel deletion as a routine troubleshooting step.

- [Troubleshooting guide](https://webhost.photonspark.com/docs/troubleshooting)