Introduction
You built a React app and npm run dev works. Now you want it on the internet, with HTTPS and a real address you can share.
Kubana App Platform does that, and for a frontend it can be free. You point it at a GitHub repository and tell it which folder your build creates (/dist for Vite). Kubana installs your packages, runs your build and serves the result over HTTPS. Links into your app, such as /recipes/42, keep working when someone refreshes the page or opens them directly, so React Router needs no extra setup.
At a glance
- Time: about ten minutes for the first deploy.
- Cost: free on the Free size (up to 2 free apps per account). Paid sizes start at a few dollars a month.
- You need: a Kubana account with App Platform access and a React app on GitHub.
- You get: your app at
https://<your-app>.platform.kubana.app, rebuilt on every push if you want.
Part 1 takes you to a live URL in seven steps. Part 2 adds deploy on push and your own domain. Part 3 shows how to do it all by asking your AI assistant.
Note: App Platform is in early access. If you don't see it in the dashboard, open App Platform and choose Request early access.
Before you start
You need:
- A Kubana Cloud account with App Platform access.
- A project in the dashboard to hold the app (Projects → New project if you have none).
- A React app in a GitHub repository, public or private, with a
package.jsonat the root.
Check that your app builds on your computer:
npm run buildIt must finish without errors and create a folder with an index.html inside. Remember that folder's name: you'll need it in Step 4.
| Your app was made with | Build folder |
|---|---|
Vite (npm create vite@latest) |
/dist |
| Create React App | /build |
Kubana installs your packages with npm, pnpm or Yarn, based on the lock file in your repository (package-lock.json, pnpm-lock.yaml or yarn.lock), then runs your build script. Commit your lock file so the build uses the same versions as your computer.
Using Next.js? A Next.js app is not a plain React app: deploy it with the Next.js framework instead. This guide is for apps that build to static files, such as Vite and Create React App.
Part 1: From GitHub to a live URL
Step 1: Create the app
In the dashboard, open App Platform and choose New app.

Fill in the form (the numbers match the screenshot):
- Project: the project the app belongs to.
- App name: a short name such as
recipes. It becomes part of your address:recipes.platform.kubana.app. If that address is taken, Kubana adds a few characters to it. - Framework: choose Frontends,
- then React.
- GitHub repository: paste
owner/repo, the HTTPS URL or the SSH URL. All three work. - App size: Free is preselected. A built React app is just files, so Free is enough for most apps. Nano and Small are paid sizes for busier sites.

Choose Review app, check the summary, then Create app and Confirm & create.

Step 2: Let Kubana read your repository
Kubana opens your new app on the Deploy key panel. A deploy key gives Kubana read-only access to this one repository: Kubana can clone your code but can never push to it.

Choose Copy key (1).
Choose Open deploy keys (2). It opens your repository's Settings → Deploy keys page on GitHub. Choose Add deploy key.
Paste the key, give it a title such as
Kubana, and leave Allow write access unchecked. Save.
Back in Kubana, choose I've added the key, verify access (3).
After a few seconds the status changes to Ready, and the next thing to do shows up in the menu as Set branch · Required.

If verification fails: check that you added the key to the same repository you entered in Step 1 and that you saved it on GitHub. Read-only access is enough.
Step 3: Pick the branch to deploy
Open Set branch. Choose Load branches, select the branch Kubana should deploy (1, usually main) and choose Save branch (2).

Kubana only deploys this branch. Pushes to other branches are ignored.
Step 4: Tell Kubana where your build goes
Once the branch is saved, the menu shows Set build directory · Required. Open it and find Build directory. Click the folder your build creates (1): /dist for Vite, /build for Create React App. Then Save build directory (2).

The path starts with / and has no spaces. If your build writes somewhere else, type that path instead.
Step 5: Add your environment variables (optional)
If your app reads settings such as an API address, add them in Environment → Add variables → Paste .env (1), then create them (2):

React only sees variables with your tool's prefix, and it reads them while building:
| Tool | Prefix | Read it with |
|---|---|---|
| Vite | VITE_ |
import.meta.env.VITE_API_URL |
| Create React App | REACT_APP_ |
process.env.REACT_APP_API_URL |
Two things follow from that:
- The values end up in the JavaScript your visitors download. Never put secrets (API keys, passwords, tokens) in a
VITE_orREACT_APP_variable. Keep them on your backend. - A change needs a new deploy. New or changed variables show as pending until your next deploy builds the app again.

Step 6: Deploy
Choose Deploy at the top right of the app page and confirm.

The status changes to Deploying. Under Deployments you can see the commit being built. A React deploy usually takes one to two minutes, and the page refreshes by itself.

Behind the scenes Kubana clones your branch, installs your packages, runs your build, and serves your build folder with nginx, set up for a single-page app.
Step 7: Open your app
When the status is Active, your public address appears next to the repository name. Choose Open app, or copy the address.

Your app is live. Share the address, and try opening one of your app's inner pages directly: it loads, because every unknown path is answered with your index.html and React Router takes over from there.
Note: On a brand new app, the HTTPS certificate can take a few minutes to be issued. If your browser warns about the certificate, wait a moment and reload.
Where to look when something is off
Deployments → Logs shows the build log: the install, your build's output and the folder being served.

Logs shows the requests your app receives.

Part 2: Make it yours
Deploy automatically on every push
To deploy every time you push to your branch:
On Configuration → Auto-deploy, turn the switch on and confirm.
Choose Show GitHub webhook details, and copy the Payload URL and the Secret.

In GitHub, open your repository → Settings → Webhooks → Add webhook. Paste the payload URL, set Content type to
application/json, paste the secret, and choose Just the push event. Save.
From now on, git push to your branch starts a deployment, labelled Auto deploy in Deployments.
Use your own domain
Every app gets a *.platform.kubana.app address. You can also attach up to five of your own domains, and HTTPS is set up for you.
First, at your DNS provider (or in Kubana DNS Management), point the domain at Kubana with the records shown in the Domains tab:
Type Host Value Required A @or your subdomain, e.g.www62.238.7.246Yes AAAA @or your subdomain2a01:4f9:c015:ef6::1Optional (IPv6) Then, in Domains, choose Add domain, enter the hostname (for example
recipes.example.rw) and attach it. Kubana checks the DNS records, then issues the certificate within a few minutes.Optionally make it the primary domain, so it becomes the app's main address.

Extra A or AAAA records that point somewhere else make verification fail. Remove them first. If your app calls an API on another domain, add your new domain to that API's allowed origins (CORS).
Part 3: Do it all by asking your AI assistant
Everything in this guide can also be done by asking an AI assistant. Kubana runs an App Platform MCP server: connect it once to Claude, ChatGPT, Claude Code, Codex, Cursor or VS Code, and your assistant can create, configure, deploy and debug your apps for you, with your account's permissions.
Connect it (about one minute)
In your assistant, add a custom connector (or MCP server) with this URL:
https://api.kubana.cloud/mcp/app-platformClaude users can also install it from the Claude directory. Setup steps for each assistant are on the MCP page.
Your browser opens Kubana. Sign in, then choose Authorize. You don't need an API key.
Then just ask
Create a free React app called recipes from github.com/acme/recipes in my Recipes project.
The assistant creates the app and gives you the deploy key. Add it on GitHub as in Step 2, then:
I've added the key. Use the main branch and the /dist build directory, set VITE_API_URL to https://api.example.com, then deploy it.
More ideas:
- "Turn on auto-deploy for recipes." The assistant gives you the webhook URL and secret to paste in GitHub.
- "Attach recipes.example.rw and make it the primary domain."
- "My last deploy failed. Read the build log and tell me why."
- "Roll back recipes to the previous deployment."
You stay in control
- Risky actions ask you first. Actions that cost money, take an app offline or touch secrets need a 6-digit code that Kubana emails you. Choose which actions need a code under MCP Servers → Approval policy. See approval codes.
- GitHub stays yours. The assistant can't touch your GitHub account, so you add the deploy key and the webhook yourself.
- Same prices, same limits. Connecting is free.
- Revoke at any time under MCP Servers → Connections.
Updating and rolling back
- New code: push to your branch (with auto-deploy) or choose Redeploy.
- New environment variables, branch or build directory: save them, then Redeploy. Saving alone doesn't change the live app.
- Something broke? In Deployments, open an earlier deployment and choose Redeploy this version. Kubana rebuilds that exact commit. Your Git history is untouched, so fix the code, then push again.
Troubleshooting
| What you see | Why it happens | What to do |
|---|---|---|
| Verification of the deploy key fails | The key is on another repository, or wasn't saved | Add it to the repository you entered at creation. Read-only is fine. |
| The deploy fails during the build | The build fails on a clean install | Run npm ci && npm run build on your computer, fix the error, commit your lock file, push. Read the build log for the exact message. |
| The deploy fails after a successful build, or the site shows a default page | The build directory doesn't match the folder your build creates | Set Build directory to /dist (Vite) or /build (Create React App), then redeploy. |
A blank page, and the browser console shows 404s for .js files |
Your build expects to live in a subfolder | Remove base from vite.config.js (or homepage from package.json for Create React App), or set it to /. |
import.meta.env.VITE_… is undefined |
Missing prefix, or no deploy since you added it | Use the VITE_ (or REACT_APP_) prefix, then redeploy so the build sees it. |
| Calls to your API fail with a CORS or mixed-content error | The API doesn't allow your domain, or it's called over http:// |
Call your API over https:// and add your app's address to the API's allowed origins. |
| You have reached the limit of 2 free apps | Each account has 2 free apps | Terminate a free app you no longer need, or pick a paid size. |
Costs at a glance
- Free size: never billed, up to 2 free apps per account, counted across all projects. Terminating a free app frees its slot.
- Nano and Small: billed hourly from your credit from the first deploy. Your balance must cover 72 hours of the size before the first deploy.
- A stopped paid app is still billed. A terminated app is not.
Conclusion
You took a React app from GitHub to a live HTTPS address, possibly for free: Kubana installed your packages, ran your build and serves it with client-side routing that works on refresh. From here you can deploy on every push, use your own domain, or let your AI assistant handle it.
Next steps:
- Deploy your first app: the short version of this guide.
- Sizes, free apps and billing.
- Fix common deploy problems.
If a deploy fails and the logs don't explain why, contact support from the dashboard. We read every message.

