Key idea
Cursor edits a project folder on your own machine, so you're already most of the way: the code is real files you own. What's left is to make it run somewhere other than your laptop, put it in a GitHub repository, and have ComputeSphere build it with your Dockerfile or a runtime build.
1. Get it into GitHub
If the folder isn't a Git repository yet, run this in Cursor's terminal, after creating an empty repository on GitHub:
git init
git add .
git commit -m "First commit"
git branch -M main
git remote add origin https://github.com/<you>/<your-app>.git
git push -u origin main
Check .gitignore first. It should list node_modules/, build output, and every .env file. If a real key was ever committed, replace it at the provider: removing the line doesn't remove it from history.
2. Make it run anywhere
Ask Cursor's agent for each fix as its own small change, and read the diff before you accept it. A brief that works:
Make this app ready to deploy. Read every secret and setting from environment variables, never from the code. Listen on 0.0.0.0 and on the port in PORT, defaulting to 8080. Add GET /healthz that returns 200 once the app can serve. Don't change anything else. List what you changed.
Then check its work yourself:
- No secrets in the code. Search for
key,secret,token,passwordand provider prefixes such assk_. - Listens on
0.0.0.0, not127.0.0.1orlocalhost, on the port inPORT. /healthzanswers when you run it:curl -i localhost:8080/healthz.- It still starts from clean: delete
node_modules(or your language's equivalent), install, and start it the way the platform will.
Commit and push.
Give Cursor's agent the deploy rules too
Cursor reads an AGENTS.md file in the project root. ComputeSphere's agent kit has one with the deploy rules written down: scoped tokens, real health checks, secrets out of code, and asking before changing anything live. Copy it in and commit it:
curl -fsSL -o AGENTS.md https://raw.githubusercontent.com/computesphere-samples/learn/main/agent-kit/AGENTS.md
Cursor can also connect to ComputeSphere's MCP server, at https://mcp.computesphere.com/mcp: add it to .cursor/mcp.json in the project or ~/.cursor/mcp.json for every project. The Claude Code guide explains what it can do and who approves it; the same applies here.
3. Dockerfile or runtime build
ComputeSphere builds your repository one of two ways. Pick one:
- Runtime build (Managed): no Dockerfile. You pick the language and version, and give a build command and a start command. Good when your app follows its language's usual layout. Node.js, Bun, Python, Ruby, Go, Rust and Elixir are supported.
- Dockerfile: you write the build down, and the image ComputeSphere runs is the one you can build and test locally with
docker build. Good when you need system packages or a particular base image.
If you want a Dockerfile, ask Cursor for a small one and read it. For a Node app with a server.js, it can be this short:
FROM node:22-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
FROM gcr.io/distroless/nodejs22-debian12:nonroot
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY server.js ./
ENV NODE_ENV=production PORT=8080
EXPOSE 8080
USER nonroot
CMD ["server.js"]
Build and run it once on your machine before you push. If it works there, it builds the same way on ComputeSphere.
4. Create the service
Start a web service
In the console, open your project (or create one under Projects, New project), then choose New service and Web Service. Name it, and choose or create an Environment.
You should seeThe New service form, starting with Service information.
Point it at the repository
Under Configuration, choose Git repository. A public repository: Public and its URL. A private one: Private (Connections), after connecting GitHub with access to only this repository (lesson 5.3.1). Set Branch, then wait a moment and check the fields below before you go on.
You should seeRepository URL and Branch filled in under Configuration.
Pick the build method
Under Runtime, choose Dockerfile (path
Dockerfile), or Managed with your Runtime environment, Version, Build command and Start command.You should seeDockerfile path filled in, or a runtime with build and start commands.
Add variables and secrets
Under Variables, add non-sensitive settings under Environment variables and keys and connection strings under Secret variables. Secrets can't be read back once saved, so keep the real values in a password manager.
You should seeEvery setting your app reads, as a variable or a secret.
Set the port and deploy
Under Networking, set Port to
8080(or whatever your app uses). Choose Deploy, then follow the build in the service's Builds tab.You should seeRunning, with a URL ending in computesphere.app.
Confirm the health check
In the service's Settings, find the Health check card. If it says Health checks not configured, choose Add health check: Endpoint path
/healthz, Port8080, Initial delay5, Check interval10. Save, then Redeploy now.You should seeThe Health check card shows Enabled, path /healthz.
To ship new code later: push, then open the service, choose Redeploy, keep Build & deploy, and confirm.
What can go wrong
| What you see | Usual cause | Fix |
|---|---|---|
| Works in Cursor, build fails on ComputeSphere | A dependency only on your machine, or a file in .gitignore the build needs | Read the first error under Builds; build from a fresh clone locally to reproduce it |
| Build passes, service never reaches Running | Listening on 127.0.0.1, or on a different port from the service's Port | Listen on 0.0.0.0 and PORT; set the same number under Networking |
| Restarts every couple of minutes | The health check path returns 404, or the app starts slower than the Initial delay | Fix the path, or raise the initial delay |
Cannot find module at start-up | A dev-only dependency used at run time, or a start command that doesn't match | Move it to dependencies; check the start command or CMD |
| A feature fails only when deployed | A variable your app reads isn't set on the service | Add it in Settings, Environment variables, then Save & redeploy |
| The agent's change "fixed" it by removing a check | It made the test pass, not the app right | Read every diff; reject changes outside the brief |