Deploy your first site

This guide takes you from nothing to a live website on Zeloxa Host. You do not need to be a developer for the first two ways. Pick the one that fits:

All three end the same way: your site is live at its own address, and you can connect your own domain afterwards.

Before you start #

• You need a Zeloxa account with Hosting. Open the dashboard and go to Hosting.
• Each site you create is a project. The project's name becomes its address (see Your site address).

Import from GitHub #

Zeloxa builds your site from your repository and publishes it. Every time you push to the chosen branch, the site is rebuilt and goes live by itself.

1. In Hosting, choose New project.
2. Choose the Import from GitHub tab.
3. If this is your first time, choose Connect GitHub. On GitHub, pick All repositories (or only the ones you want), then approve. You come back to Zeloxa with your repositories listed.
4. Find your repository (use the search box) and choose Import.
5. Check the Project name and the Branch. The branch is usually main. Every push to it deploys.
6. Optional: open Build settings to set a root directory, build command or output directory. Leave them blank and Zeloxa works them out from your package.json (see Build settings).
7. Choose Deploy.

What you'll see: the project's Git tab, with the first build already running. Open it to follow the build log line by line. When it finishes, the site is live at its address.

Only repositories you can push to are listed. Missing one? Use the Give Zeloxa access to it on GitHub link under the list, add it on GitHub, then refresh the list.

Upload a folder #

Use this when you already have the finished website files: an index.html with its images, styles and scripts. Zeloxa publishes the files exactly as they are. It does not run a build.

1. In Hosting, choose New project.
2. Choose the Upload a build tab.
3. Type a Project name and choose Create project.
4. You land on the project's Deployments tab.
5. Put your website folder in a .zip file. On a Mac, right-click the folder and choose Compress. On Windows, right-click and choose Send to → Compressed (zipped) folder.
6. Drag the .zip onto the upload area, or choose Choose a .zip.

What you'll see: "Uploading and publishing…", then "Deployment #1 is live with N files." The site is live straight away.

Rules for the zip:

• It must be a .zip. Other archive types are refused.
• index.html must be at the top, or inside one folder that holds everything (zipping the folder itself or its contents both work).
• If you built the site with a tool, zip the output folder (often dist, out or build), not the whole project folder. If you zip the project folder, you will see: "No index.html or _worker.js at the top of the build."
• System files (.DS_Store, __MACOSX, ._* files), .git and node_modules folders are skipped automatically.
• The size limits are in Limits.

To update the site later, upload a new zip. Each upload becomes a new deployment and goes live as soon as it is stored.

Deploy from the command line #

The zeloxa command deploys a folder from your terminal or from CI. You need Node.js 18.17 or newer and an API token.

1. In the dashboard, go to Hosting → API tokens and create a token with the host:deploy scope. It is shown once, so copy it.

2. In your project folder, run:

   npx zeloxa login     # paste the token when asked
   npx zeloxa link      # pick the site this folder deploys to
   npm run build        # or however your project builds
   npx zeloxa deploy    # uploads dist, out or build, whichever has files

What you'll see: progress while the CLI scans, packs and uploads, then the site's address. The deployment is live when the command finishes.

The CLI guide covers everything else: choosing the folder, .zeloxaignore, GitHub Actions and troubleshooting.

Build settings #

These apply when Zeloxa builds your site from GitHub. Change them at any time on the project's Git tab: choose Edit settings, then Build settings.

Paths must stay inside the repository: no leading / and no ... Commands cannot contain ;, &, |, $, >, < or backticks. Put several steps in a package.json script and run that instead.

Framework detection #

Zeloxa reads package.json in the root directory and looks for a known framework in dependencies or devDependencies. The first match wins.

Next.js, Nuxt, Remix and SvelteKit are treated as full-stack frameworks. If your site is a static export, set Output directory to the folder the export writes, for example out for a Next.js static export (output: "export").

When no framework is found:

• With a build script in package.json: Zeloxa runs npm run build and publishes dist.
• With no build script, or no package.json at all: the files are published as they are. This is right for a hand-written HTML site.

The install command follows your lockfile:

What you'll see: near the top of every build log, a line such as "Framework: Astro. Install: npm ci. Build: npm run build. Output: dist." If the output directory is wrong, the build stops with "The build finished but dist does not exist. Set the output directory to the folder your build writes."

Node.js version #

Choose Automatic, 24.x or 22.x.

Automatic reads the engines.node field in your package.json and uses the newest version it allows. For example ">=20" gets 24, and "^22" or "22.x" gets 22. With no engines field, or one that allows neither version, the build uses 22.

What you'll see: a line such as "Node v24.x.x, npm 10.x.x" in the build log.

Environment variables #

Add API keys and settings your build reads in Settings → Environment variables. They are used by builds from GitHub, not by uploads or the CLI (those are built on your own computer). See the environment variables guide.

What is never published #

Builds from GitHub never publish source maps (*.map), .env files, .git or node_modules, even if they are in the output directory.

Your site address #

Every project gets a free address: <name>.zeloxa.app. The name comes from the project name: lowercase, with spaces and symbols turned into hyphens. "My Restaurant Site" becomes my-restaurant-site.zeloxa.app. The form shows the address as you type.

• Very short names (under 3 characters) and reserved words such as www, admin or shop get -site added, for example shop-site.zeloxa.app.
• If the name is already taken by another site, a short random ending is added, for example my-restaurant-site-3f9a1c.zeloxa.app.
• Names that contain "zeloxa" are refused, so no site can pass itself off as Zeloxa.

The address keeps working after you add your own domain. To use your own domain, see Connect a custom domain.

What happens on each push #

When your project is connected to GitHub:

Previews are explained in the previews guide.

Good to know:

• One build at a time per site. If you push while a build is running, the newest waiting commit builds as soon as the current build ends. Older waiting commits are skipped, so you always end up with your latest code.
• Two builds at a time per organization. A production build waits its turn. A preview build is skipped instead; the next push to that branch builds it.
• Turn off automatic deploys on the Git tab (Edit settings, untick Deploy automatically on every push). Then nothing builds on push, and you start builds with Deploy now.
• Rebuild without pushing: choose Deploy now on the Git tab, or use a deploy hook.
• Disconnecting the repository stops new builds. Deployments already made stay live.

What you'll see: on GitHub, a check next to each commit ("Building…", then "Deployed" or "Build failed"). Its Details link opens the live site or the build log.

Skip a build #

To push without building, put one of these anywhere in the commit message: [skip ci], [ci skip] or [skip zeloxa]. Upper or lower case both work.

git commit -m "Fix a typo in the README [skip ci]"

The keyword is read from the newest commit in the push. It applies to pushes to your production branch and to other branches. Pull requests always build.

What you'll see: on GitHub, a green check that says "Build skipped: [skip ci] in the commit message". On the Git tab, the push is listed under Recently skipped pushes.

Watch paths #

Watch paths are for repositories that hold more than one site (a monorepo). A push only builds this site if it changes a file inside its watch paths.

Set them on the Git tab: choose Edit settings, open Build settings, and fill in Watch paths, one per line (up to 20):

apps/web/**
packages/ui/**
!**/*.md

If you leave it blank, a push builds when it changes something under the Root directory, or on any change when no root directory is set.

Some pushes always build, because GitHub does not list their changes in full: the first push of a new branch, a force push, and very large pushes. Pull requests, Deploy now and deploy hooks always build too.

What you'll see: a skipped push gets a green check on GitHub that says "Build skipped: no changes in this site's watch paths", and appears under Recently skipped pushes with "Skipped: no watched changes".

Build cache #

Zeloxa keeps your dependency downloads and your framework's own build cache between builds, so later builds skip most of the install. There is nothing to set up.

• Builds of your production branch save the cache. The next build reuses it.
• Previews use the cache but never change it.
• The cache only speeds up the install. Your install command still runs in full, so the result is the same as a fresh install.

What you'll see: a line such as "Restored build cache (180 MB, from 2 hours ago)." in the build log.

If a build behaves differently from a fresh install:

• To rebuild once without the cache, choose Redeploy without cache next to a build on the Git tab.
• To delete the cache completely, choose Clear build cache in the Build cache section of the Git tab. The next build installs everything from scratch.

Roll back #

Every deployment is kept, so going back is instant. Nothing is rebuilt.

1. Open the project's Deployments tab.
2. Find the deployment you want. Only deployments marked ready can be served.
3. Choose Roll back (for an older one) or Promote (for a newer one).

What you'll see: "Rolled back. Deployment #N is live again." The site switches within seconds.

From the command line, npx zeloxa rollback goes back to the deployment before the live one, and npx zeloxa rollback 3 goes to deployment #3. See rollback in the CLI guide.

The next push to your production branch still deploys as normal. To keep the rolled-back version live while you fix things, turn off automatic deploys on the Git tab first.

Limits #

Your current usage is on Hosting → Usage.

Next steps #

• Connect a custom domain
• Preview branches and pull requests
• Add environment variables
• Rebuild from your CMS with a deploy hook
• Set up redirects and headers