Why does my AI-built app work on my laptop and fail when I deploy it?
The app runs perfectly on your machine, then builds and serves nothing, or loses its data overnight. The eight causes behind almost every case, each with the fix, whichever host you use.
Your agent built a tool for the team. On your laptop it works: you open localhost:3000, add a few rows, click around. Then you deploy it, and one of three things happens. The build fails. The build succeeds and the address shows nothing. Or it works for a day, and the next morning everything anyone entered is gone.
None of these means the agent wrote bad code. The code was written for one computer, yours, and a server is a different kind of computer. Almost every case comes down to the eight causes below.
We make Spryloom, which runs apps like this for teams behind sign-in, and it comes up near the end. The causes and fixes apply to any host: a platform that runs containers, a VPS, or ours.
Your laptop is forgiving. A server isn't.
On your laptop the app has everything: tools you installed years ago, files in your home folder, a .env from week one, and a process that runs because you never close the terminal. A server starts from a clean copy of the repository and gives the app only what it is told to.
Start from what you see, then read that fix.
1. A fixed port
Locally, the app listens on 3000 because the agent picked 3000. On a server, the host picks the port and passes it in an environment variable, usually PORT. An app that ignores it builds, starts, and serves nothing, because requests arrive on a port nobody is listening to.
Fix: read the port from the environment, and keep a default for your laptop.
server.listen(process.env.PORT || 3000, '0.0.0.0');
2. Listening on 127.0.0.1
The second half of that line matters as much. 127.0.0.1, also called loopback or localhost, means "only this computer". On a server the app runs in its own container, so loopback means only that container, and the host's traffic arriving from outside is never answered.
Fix: bind to 0.0.0.0, which means "every network the machine has". Some frameworks bind to loopback by default in development mode; check the start command uses the production setting.
3. Settings in a file, or a committed .env
Agents often put the database address, an API key or a feature flag in a config file or .env. If the .env is committed, your keys are in the repository's history for good. If it isn't, the server has no .env, and the app starts with every setting missing.
Fix: read every setting from the environment, and set the values on the host. Keep .env in .gitignore for local use only. For where the keys themselves should live, see Where should the API keys go in an app you built with AI?
4. No lockfile
package.json says roughly which versions the app wants, such as "version 4 or anything newer in 4". The lockfile, package-lock.json, says exactly which versions you tested. Without it, the server installs whatever is newest that day.
Fix: run npm install and commit package-lock.json. Related: a package your code imports but that isn't in package.json, because it happened to be installed globally on your machine, works locally and fails the build with "cannot find" that package. Install it into the project so it is listed.
5. No start script
You start the app by typing node server.js, or by a command the agent ran for you. The server has no idea what you typed.
Fix: say it in package.json, where every host looks.
{ "scripts": { "start": "node server.js" } }
6. Your machine, assumed
Builds run on a clean machine with nothing but the repository and its dependencies. Anything else the code relies on is missing there:
- Global tools you installed once and forgot about.
- Absolute paths such as
/Users/you/projects/data.csv. - Files outside the project folder, like a spreadsheet in Downloads the app reads on start.
- File name case. A Mac usually treats
Report.jsandreport.jsas the same file. Linux servers don't, so an import with the wrong case works locally and fails there.
Fix: everything the app needs is in the repository or installed by npm install, and paths are relative to the project.
7. Writing files that disappear
The agent's quickest way to remember something is a JSON file next to the code. Your laptop's disk is permanent, so it works. On most servers the app's disk is rebuilt from the image on every deploy and restart, and on some hosts, Spryloom included, it is read-only apart from a temporary folder.
A JSON file next to the code
- Still there tomorrow on your laptop
- Rebuilt away on every deploy and restart
- Refused where the disk is read-only
A database
- Survives deploys and restarts
- Tables made on start with
CREATE TABLE IF NOT EXISTS - A first deploy needs no extra step
8. Timers inside the server
"Email everyone at 9" often becomes setInterval or a cron library inside the server. Many hosts stop an app when nobody is using it, and the timer stops with it. The 9:00 email never goes out, and nothing says why.
Fix: use the host's scheduled jobs, so the schedule lives outside the app. How to send a daily email reminder from an app you built with AI covers this one in detail.
Fix it in the agent, not after the fact
Each of these is easier to prevent than to diagnose. A short instruction file in the project with these eight rules works with any agent, and the first deploy is the one that works:
- Read
PORT. Keep 3000 as the laptop default. - Bind to
0.0.0.0. Not loopback. - Settings from the environment.
.envstays in.gitignore. - Commit the lockfile. Every import listed in
package.json. - A start script. In
package.json. - Nothing from your machine. Relative paths, correct file name case.
- Data in a database. Never a file on the server's disk.
- Scheduled jobs. No timers inside the server.
Telling the agent after a failure works too, but you will meet the next one on the next app.
Where Spryloom fits
Spryloom's skill gives your coding agent these rules while it builds, with Postgres for data and declared jobs for schedules. When the agent gets one wrong, the skill tells it the mistake is the agent's to fix, not yours.
# what Spryloom sees, and whether it could publish; changes nothing spry check spry publish # a failure names the cause; the fixed-port case says: The app built, but it isn't accepting requests. # the version that was live keeps serving
Each app also gets its own Postgres database, with DATABASE_URL set for it, so cause 7 has somewhere to go.
What it doesn't do
- It is Node only. A Python app needs another host.
- No file uploads. Apps can't accept and keep files people upload; that is refused when declared.
- Jobs run at most once every 10 hours. A daily or twice-daily job is fine. Something that must run every minute is the wrong fit.
- It is for people you know. Everyone who opens the app signs in. A public site belongs on a normal host, where the same eight fixes apply.
Start here
In the app's folder:
npx -y spryloom check
npx -y spryloom publish
In Claude Code, add the plugin so the agent follows these rules while it builds:
/plugin marketplace add spryloom/claude-plugin
/plugin install spryloom@spryloom