# PhotonSpark Webhost documentation

Public deployment guides for humans and AI agents. No login required to read or download. Account access is required to create or change resources.

- [Build with PhotonSpark](https://webhost.photonspark.com/docs): Deploy a website, ship a full-stack app, or bring a local service online with SparkTunnel. Guides for developers and the AI agents working with them.
- [Deploy a Site](https://webhost.photonspark.com/docs/sites): Publish static files, a compiled frontend, or a production Node server from a repository or ZIP.
- [Deploy a full-stack App](https://webhost.photonspark.com/docs/apps): Build a frontend and backend from one repository, with a scoped shared PostgreSQL database.
- [SparkTunnel & downloads](https://webhost.photonspark.com/docs/sparktunnel): Publish a service running on your computer, a Docker host, or a private network through a public HTTPS hostname.
- [Domains & HTTPS](https://webhost.photonspark.com/docs/domains): Connect a hostname, verify DNS delegation, and let Webhost manage its certificate.
- [Environment & secrets](https://webhost.photonspark.com/docs/environment): Put configuration where it is used: during the build, in a Node runtime, or in an App's backend.
- [Deployment workflow](https://webhost.photonspark.com/docs/deployments): Prepare, publish, verify, and recover a customer release with clear evidence at each step.
- [Troubleshoot a deployment](https://webhost.photonspark.com/docs/troubleshooting): Find the failing layer before changing a working configuration.
- [Build with an AI agent](https://webhost.photonspark.com/docs/agents): Give your coding assistant a public, inspectable deployment contract and a clear verification task.

Full text: https://webhost.photonspark.com/docs/llms-full.txt
Preview downloads: https://webhost.photonspark.com/api/v1/client-apps/spark-tunnel-preview
Legacy downloads: https://webhost.photonspark.com/api/v1/client-apps


# Build with PhotonSpark

Deploy a website, ship a full-stack app, or bring a local service online with SparkTunnel. Guides for developers and the AI agents working with them.

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

## Choose how your project runs

Start with the service you need to publish. A Site hosts one website origin. An App deploys a frontend and backend together. SparkTunnel keeps the application on your own machine.

- [Sites — static files, frontend builds, and Node servers](https://webhost.photonspark.com/docs/sites)
- [Apps — frontend, backend container, and shared PostgreSQL](https://webhost.photonspark.com/docs/apps)
- [SparkTunnel — publish a local service and download connectors](https://webhost.photonspark.com/docs/sparktunnel)

## From repository to public hostname

1. Prepare your project using the matching guide. Copy its AI prompt or use a Site starter to give your coding agent the deployment contract.
2. Sign in to Webhost to create a Site or App and select a hostname you control. Reading these docs and downloading clients do not require an account.
3. Configure DNS, connect the repository or upload a release, and add environment variables in the correct scope.
4. Deploy, then check build logs, runtime readiness, HTTPS, and your application's real routes.

- [Deployment workflow](https://webhost.photonspark.com/docs/deployments)
- [Domains and HTTPS](https://webhost.photonspark.com/docs/domains)

## Give your agent the same instructions

Every guide has a copyable AI prompt and a plain-text version. The Site guide also includes the same starter files used in the dashboard. Use placeholders for credentials; supply secrets through the dashboard or a protected local prompt.

- [Working with AI agents](https://webhost.photonspark.com/docs/agents)
- [Complete documentation as text](https://webhost.photonspark.com/docs/llms-full.txt)


---

# Deploy a Site

Publish static files, a compiled frontend, or a production Node server from a repository or ZIP.

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

## Choose the build mode

A Site builds from the repository root. It does not read platform.app.yaml or build a backend Dockerfile. Choose an App when you need a separately deployed backend and managed PostgreSQL.

Keep server rendering, authentication, and API routes on node-server when they need a running server. Static output alone cannot run those features.

- static: Ready-to-serve HTML, CSS, JavaScript and images. No install or build command runs. Publish the first directory containing index.html: repository root, public, dist, build, out.
- node-static: React/Vite and other frontends that compile to static files. No server stays running. Install dependencies → npm run build → publish the first matching output: dist, build, out, .output/public.
- node-server: A production Node process for server rendering or routes such as a contact API. Install dependencies → npm run build → npm prune --omit=dev → deploy → npm start.

## Repository structure

With a committed npm lockfile the builder uses npm ci; otherwise it uses npm install. Both Node build modes require a build script. A static Site needs ready-to-publish files including index.html.

For Vite/React, keep your normal build command and choose node-static. The generated dist directory is published; vite dev and vite preview are not production startup requirements.

```text
my-site/
  package.json          # build; also start for node-server
  package-lock.json     # commit the lockfile
  src/                  # your application source
  public/               # assets or starter input
  .gitignore            # exclude node_modules and private .env files
```

## Copy or download a starter

Choose a mode below to view its files, download the complete ZIP, or copy an AI prompt. These minimal Node starters use no external packages: their build copies public files into dist. Adapt them to an existing project rather than replacing its features.

## Production runtime contract

- node-server is installed and built before startup, then development dependencies are pruned. Packages needed at runtime belong in dependencies.
- npm start, prestart, and poststart must only start the production server. Do not install packages, rebuild, or launch a development server at startup.
- Bind to 0.0.0.0 and honor process.env.PORT; the default Site port is 3000. Webhost provides HOST, HOSTNAME, PORT, and NODE_ENV.
- The release under /app is read-only. /tmp is temporary and does not survive replacement. Use a persistent external service for durable data.
- A Site does not automatically receive an App database.

```sh
npm ci
npm run build
npm prune --omit=dev
npm start
# In another terminal, test the application and its real routes:
curl --fail http://127.0.0.1:3000/
```

## Connect and deploy

For manual static publishing, choose the upload method and supply a folder or ZIP with the intended publish-root files. A root index.html is the simplest layout. Check the uploaded release before switching traffic.

1. Create a Site, choose Git Auto Deploy, and enter the repository, branch, and matching build mode.
2. For private SSH repositories, install the displayed public deploy key with read-only repository access and verify the server key. HTTPS token credentials are entered in the dashboard.
3. Set build-time public values and runtime secrets in Environment. Commit the source and lockfile, then deploy the latest commit.
4. Check the build log, runtime state, HTTPS hostname, and all required application routes. Later commits can be picked up by Git polling.

- [Environment variables](https://webhost.photonspark.com/docs/environment)
- [Troubleshooting](https://webhost.photonspark.com/docs/troubleshooting)

## Reference starter files

## .gitignore

```
node_modules/
dist/
.env
.env.*
!.env.example
*.log
```

## index.html

```
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>My site</title></head>
<body><main><h1>Hello from my site</h1><p>Published with PhotonSpark.</p></main></body>
</html>
```

## 404.html

```
<!doctype html>
<html lang="en"><head><meta charset="utf-8"><title>Page not found</title></head>
<body><h1>Page not found</h1><a href="/">Return home</a></body></html>
```

## README.md

```
# PhotonSpark Site starter

Choose **Static files** (static) in Site → Git Auto Deploy.

Publish the first directory containing index.html: repository root, public, dist, build, out.

Commit the files in this folder at the repository root. Node examples have no
external dependencies; their build copies public/ to dist/. Adapt the build script
to your framework and update package-lock.json when adding dependencies.

No npm commands are needed.
Static hosting cannot execute a contact handler or other server API.

Connect the repository and branch in the dashboard. For private SSH repositories,
install the displayed public deploy key with read-only access, then deploy.
Keep credentials in Environment, never in Git or browser bundles.
Guide: https://webhost.photonspark.com/dashboard/site-deployment
```


## .gitignore

```
node_modules/
dist/
.env
.env.*
!.env.example
*.log
```

## package.json

```
{
  "name": "photon-site-static",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "node scripts/build.mjs"
  },
  "engines": {
    "node": ">=22"
  }
}
```

## package-lock.json

```
{
  "name": "photon-site-static",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "photon-site-static",
      "version": "1.0.0",
      "engines": {
        "node": ">=22"
      }
    }
  }
}
```

## public/index.html

```
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>My site</title></head>
<body><main><h1>Hello from my site</h1><p>Published with PhotonSpark.</p></main></body>
</html>
```

## public/404.html

```
<!doctype html>
<html lang="en"><head><meta charset="utf-8"><title>Page not found</title></head>
<body><h1>Page not found</h1><a href="/">Return home</a></body></html>
```

## scripts/build.mjs

```
import { cp, mkdir, rm } from "node:fs/promises";
const output = new URL("../dist/", import.meta.url);
await rm(output, { recursive: true, force: true });
await mkdir(output, { recursive: true });
await cp(new URL("../public/", import.meta.url), output, { recursive: true });
```

## README.md

```
# PhotonSpark Site starter

Choose **Node build (npm run build)** (node-static) in Site → Git Auto Deploy.

Install dependencies → npm run build → publish the first matching output: dist, build, out, .output/public.

Commit the files in this folder at the repository root. Node examples have no
external dependencies; their build copies public/ to dist/. Adapt the build script
to your framework and update package-lock.json when adding dependencies.

Test with npm ci and npm run build. Commit package-lock.json; do not commit node_modules/.
Static hosting cannot execute a contact handler or other server API.

Connect the repository and branch in the dashboard. For private SSH repositories,
install the displayed public deploy key with read-only access, then deploy.
Keep credentials in Environment, never in Git or browser bundles.
Guide: https://webhost.photonspark.com/dashboard/site-deployment
```


## .gitignore

```
node_modules/
dist/
.env
.env.*
!.env.example
*.log
```

## package.json

```
{
  "name": "photon-site-server",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "node scripts/build.mjs",
    "start": "node server/index.mjs"
  },
  "engines": {
    "node": ">=22"
  }
}
```

## package-lock.json

```
{
  "name": "photon-site-server",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "photon-site-server",
      "version": "1.0.0",
      "engines": {
        "node": ">=22"
      }
    }
  }
}
```

## public/index.html

```
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>My site</title></head>
<body><main><h1>Hello from my site</h1><p>Published with PhotonSpark.</p></main></body>
</html>
```

## public/404.html

```
<!doctype html>
<html lang="en"><head><meta charset="utf-8"><title>Page not found</title></head>
<body><h1>Page not found</h1><a href="/">Return home</a></body></html>
```

## scripts/build.mjs

```
import { cp, mkdir, rm } from "node:fs/promises";
const output = new URL("../dist/", import.meta.url);
await rm(output, { recursive: true, force: true });
await mkdir(output, { recursive: true });
await cp(new URL("../public/", import.meta.url), output, { recursive: true });
```

## server/index.mjs

```
import http from "node:http";
import { readFile } from "node:fs/promises";

// Read the completed build. Startup never installs packages or rebuilds.
const index = await readFile(new URL("../dist/index.html", import.meta.url));
const notFound = await readFile(new URL("../dist/404.html", import.meta.url));
const port = Number(process.env.PORT || 3000);
const host = process.env.HOST || "0.0.0.0";
const server = http.createServer((req, res) => {
  let path;
  try { path = new URL(req.url || "/", "http://localhost").pathname; }
  catch { res.writeHead(400); res.end(); return; }
  if (path === "/healthz") {
    res.writeHead(200, { "content-type": "application/json" });
    res.end(JSON.stringify({ ok: true }));
    return;
  }
  const found = path === "/" || path === "/index.html";
  res.writeHead(found ? 200 : 404, { "content-type": "text/html; charset=utf-8" });
  res.end(found ? index : notFound);
});
server.listen(port, host);
process.on("SIGTERM", () => server.close());
process.on("SIGINT", () => server.close());
```

## README.md

```
# PhotonSpark Site starter

Choose **Node server (npm start)** (node-server) in Site → Git Auto Deploy.

Install dependencies → npm run build → npm prune --omit=dev → deploy → npm start.

Commit the files in this folder at the repository root. Node examples have no
external dependencies; their build copies public/ to dist/. Adapt the build script
to your framework and update package-lock.json when adding dependencies.

Test with npm ci and npm run build. Commit package-lock.json; do not commit node_modules/.
Then run npm prune --omit=dev and npm start. Start only the built production server.
/app is read-only; use /tmp only for temporary files. Keep runtime packages in dependencies.
Listen on 0.0.0.0 and process.env.PORT (3000 by default). Preserve your existing API routes.

Connect the repository and branch in the dashboard. For private SSH repositories,
install the displayed public deploy key with read-only access, then deploy.
Keep credentials in Environment, never in Git or browser bundles.
Guide: https://webhost.photonspark.com/dashboard/site-deployment
```



---

# Deploy a full-stack App

Build a frontend and backend from one repository, with a scoped shared PostgreSQL database.

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

## Organize the repository

The standard manifest is platform.app.yaml at the repository root; the manifest path is configurable in Webhost. Frontend buildMode accepts static, node-static, or node-server. Paths are relative to the repository; the Dockerfile path is relative to backend.path.

```text
my-app/
  platform.app.yaml
  frontend/
    package.json
    package-lock.json
    src/
  backend/
    Dockerfile
    .dockerignore
    package.json
    package-lock.json
    src/
```

## Describe the deployment

This example expects a real npm run migrate script in the backend. Omit migrations if you have no migration command. App deployment currently provisions shared PostgreSQL even if the database block is omitted; omission is not a database-disable switch. Your application may leave the database unused. dedicated-ha is reserved and is not provisioned by this platform version.

```yaml
version: 1
frontend:
  path: frontend
  buildMode: node-static
backend:
  path: backend
  dockerfile: Dockerfile
  port: 8080
  healthPath: /healthz
# Shared PostgreSQL is the current App default. Migrations are optional.
database:
  postgres:
    tier: shared
    migrations:
      command: npm run migrate
routing:
  apiPrefix: /api
```

## Package the backend

The backend must listen on 0.0.0.0 at backend.port and serve backend.healthPath. routing.apiPrefix must be /api in this platform version. Keep application endpoints under /api; the gateway preserves that prefix. Return a successful response from the configured health route.

Compile TypeScript or other source during the image build. Start the compiled production entry point. Exclude .env, credentials, node_modules, and unrelated files from the Docker build context.

```dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev --no-audit --no-fund
COPY --chown=node:node src/ ./src/
ENV NODE_ENV=production HOST=0.0.0.0 PORT=8080
USER node
EXPOSE 8080
CMD ["node", "src/server.js"]
```

## Connect the database and frontend

- The shared PostgreSQL service gives the app a scoped user and schema. Read DATABASE_URL from the backend environment; never commit it or put it in browser code.
- The optional migration command runs separately using the app database credentials. Make migrations safe to retry and consider compatibility with the currently serving application.
- Browser code calls /api on the application's public hostname. Server-rendered frontend code can use process.env.BACKEND_INTERNAL_URL to reach its own backend.
- The backend also receives FRONTEND_INTERNAL_URL. These internal URLs are server-only settings.
- Do not rely on container memory or local files for durable user data. Use PostgreSQL or another explicitly configured persistent service.

## Build, deploy, and verify

A successful build alone does not prove the backend starts or the application works. A Git polling warning can coexist with a healthy older release.

1. Create an App, connect the repository and branch, and select its manifest path.
2. Configure build, frontend, and backend environment values. Keep secrets out of frontend bundles.
3. Run the deployment. Webhost builds the frontend, builds and publishes the backend image, provisions shared PostgreSQL, and runs the configured migration.
4. Inspect build logs and both runtime components. Verify the homepage, backend health route, real API requests, and database behavior through the public hostname.

- [Frontend Site build contracts](https://webhost.photonspark.com/docs/sites)
- [Deployment workflow](https://webhost.photonspark.com/docs/deployments)


---

# 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)


---

# Domains & HTTPS

Connect a hostname, verify DNS delegation, and let Webhost manage its certificate.

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

## Connect a domain you control

Use direct-a or alias-cname according to the dashboard's setup instructions. Do not copy server IP addresses from old tutorials. DNS propagation and caching can delay what different resolvers see.

1. Add your zone using PhotonSpark DNS or connect a supported Cloudflare account.
2. For PhotonSpark DNS, set the domain's nameservers at your registrar to the exact nameservers shown by Webhost. Adding a zone in Webhost alone does not change the registrar.
3. Check delegation status. Needs delegation means Webhost has not verified the parent DNS delegation it requires.
4. Create the Site or App hostname and use the DNS records Webhost provides. If DNS is managed elsewhere, add the required records there.

## Enable HTTPS

Select the supported TLS mode for the resource. The usual HTTP-01 flow requires the hostname to reach the platform so the certificate challenge can complete. DNS-01 through Cloudflare requires the appropriate zone access.

Check the Certificates or TLS view for issuance status and errors. Enable HTTP-to-HTTPS redirects after checking the intended route. Do not repeatedly recreate the resource to retry certificate issuance.

- [Deployment verification](https://webhost.photonspark.com/docs/deployments)

## Check each layer separately

Replace the example hostname and health path with your application's values. DNS resolution, TLS issuance, proxy connectivity, and an application's own HTTP response are separate checks. A certificate being Ready does not establish application health.

```sh
dig NS example.com
dig A app.example.com
curl -I https://app.example.com/
curl --fail https://app.example.com/api/healthz
```


---

# Environment & secrets

Put configuration where it is used: during the build, in a Node runtime, or in an App's backend.

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

## Choose the right scope

- Site build: values consumed while building the artifact. Public framework variables can become part of browser JavaScript.
- Site runtime: values available to the running Node server. Static sites have no server process reading runtime variables.
- App frontend and backend: settings for the corresponding running component. Build values are separate.
- Public VITE_* or NEXT_PUBLIC_* values are not secrets. Changing a compiled public value requires a new build.

## Keep credentials out of source and prompts

Use Webhost's secret-value controls. Secret values are write-only after saving; masking is not a value to paste back into configuration. Preserve existing variables when making unrelated changes.

Never commit .env files, database URLs, API tokens, deploy private keys, or enrollment grants. Copyable documentation uses placeholders; fill them through the dashboard or a protected local input, not a shared AI transcript.

## Use the injected runtime settings

- Node Sites: respect HOST, HOSTNAME, PORT, NODE_ENV, HOME, and NPM_CONFIG_CACHE supplied by the runtime.
- Apps: use BACKEND_INTERNAL_URL for server-side frontend calls and FRONTEND_INTERNAL_URL for backend-to-frontend calls.
- Managed App PostgreSQL: use the supplied DATABASE_URL in the backend. Browser code calls your API rather than connecting directly to PostgreSQL.

- [App database and routing contract](https://webhost.photonspark.com/docs/apps#database)


---

# Deployment workflow

Prepare, publish, verify, and recover a customer release with clear evidence at each step.

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

## Prepare the project

1. Choose Site, App, or SparkTunnel before changing the repository structure.
2. Inspect the existing project and preserve its APIs, authentication, and stored data.
3. Run the relevant build and production startup checks. Test the real application routes.
4. Review the diff and commit only the intended source, configuration, and lockfile changes. Keep generated caches and credentials out of Git.

```sh
git status --short
git diff --check
git diff
# Stage only the files you reviewed, then:
git commit -m "Prepare PhotonSpark deployment"
git push origin YOUR_BRANCH
```

## Publish through Webhost

For Git-connected resources, push the configured branch and let polling detect it, or request a deployment in the dashboard. Polling runs periodically; it is not an instant push webhook.

A build selects a source revision, produces artifacts, and creates a release. The running deployment can stay on its previous release if the new build fails. Inspect the build and runtime status separately.

For uploaded Sites, create a release from the intended publish files. For SparkTunnel, start and approve the connector, then activate the desired transport through its own workflow.

## Verify the public result

- Confirm the deployed revision matches the intended commit or uploaded release.
- Read build logs and check runtime startup and readiness.
- Open the public hostname and test HTTPS, assets, login, forms, API routes, and WebSockets or streaming if your application uses them.
- For Apps, test frontend-to-backend and database operations. A healthy frontend alone does not verify the backend.
- For SparkTunnel, test the local target and the public hostname independently.

## Recover deliberately

For an uploaded or Git-built Site, use its supported release rollback control to select a known working release. Check configuration and database compatibility before reverting an application.

Reverting code does not undo database migrations or restore deleted data. Use a reviewed database recovery procedure when data must change. Do not delete a Site, App, or connector to conceal a deployment failure.

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


---

# Troubleshoot a deployment

Find the failing layer before changing a working configuration.

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

## Build or startup failure

- EROFS / read-only filesystem: startup is trying to modify the deployed artifact. Install and build earlier; use /tmp only for disposable files.
- Missing vite or a compiler at startup: development dependencies were pruned. Run the compiled server, or select node-static for a static build.
- Missing publish directory: check the selected build mode and ensure the build produces index.html in a supported output directory.
- Connection refused / runtime not Ready: inspect startup logs, bind to 0.0.0.0, and match the configured port and health path.
- Git fetch error: check repository access, branch, deploy key or HTTPS token, and the verified SSH host key. An upstream failure can leave an older release serving normally.

## Public hostname failure

- DNS does not resolve: check registrar delegation and the required A/CNAME records before changing the application.
- TLS error: inspect certificate issuance and DNS/challenge reachability.
- HTTP 404: check whether the route exists in your application and whether the correct release is serving. A reachable origin may intentionally return 404.
- HTTP 401: check whether application authentication or an App's Basic Auth gate is expected.
- HTTP 502 for SparkTunnel: verify the connector process, its network connection, and reachability of the configured local target.
- Frontend works but API fails: verify routing.apiPrefix, the backend health route, and the URL the frontend actually calls.

## Give an agent useful evidence

Share the chosen deployment method, build mode, sanitized manifest, intended hostname, source revision, HTTP status, and the relevant error excerpt. Remove tokens, cookies, database URLs, and other credentials.

Ask the agent to identify the failing layer and propose the smallest change that preserves working behavior. A browser console without errors does not rule out stale status, upstream failures, or a server-side problem.

- [Copy an agent brief](https://webhost.photonspark.com/docs/agents)


---

# Build with an AI agent

Give your coding assistant a public, inspectable deployment contract and a clear verification task.

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

## Start with the matching guide

Use Copy AI prompt on a guide to copy its contract and source URL. The Site starter panel creates a mode-specific prompt with its reference files. Agents that cannot render pages can read the plain-text endpoints below.

- [Documentation index for agents](https://webhost.photonspark.com/llms.txt)
- [Complete documentation as text](https://webhost.photonspark.com/docs/llms-full.txt)
- [Site templates and prompts](https://webhost.photonspark.com/docs/sites#starters)

## Add your project's requirements



```text
Prepare my existing project for PhotonSpark Webhost.
Read https://webhost.photonspark.com/docs/llms-full.txt first.
Deployment: Site / App / SparkTunnel (choose one)
Framework and version: ...
Repository branch: ...
Public hostname: app.example.com
Features to preserve: login, API routes, uploads, WebSockets, ...
Persistent data: ...
Inspect before editing. Explain the required structure and build/runtime commands.
Keep credentials out of the repository and this conversation.
Implement the smallest complete change and test production startup and real routes.
Report changed files, dashboard settings, validation results, and remaining limits.
Do not deploy, delete data, or change DNS until I authorize those actions.
```

## Ask for evidence, not just generated files

- Exact repository structure and selected Site build mode or App manifest.
- A lockfile and reproducible production build steps.
- Environment variable names and scopes, with placeholders for secrets.
- Local verification plus public-route checks after an authorized deployment.
- Known limitations, failed checks, and recovery considerations.