Deploy with Claude Code or Cursor to your own server, safely
How to deploy with Claude Code or Cursor: let the agent prepare the repo and push to Git, then deploy on push or from CI, without giving it your server keys.

Key takeaways
- The safest way to deploy with Claude Code or Cursor is to let the agent change the repository and push to Git, and let the server deploy from Git, so the agent never holds server credentials.
- A deployable repository listens on the port in $PORT, reads its configuration from environment variables, has explicit build and start commands, a health check path and a .gitignore that keeps secrets out.
- Claude Code reads CLAUDE.md or AGENTS.md at the start of every session, and Cursor reads AGENTS.md and .cursor/rules, so deployment rules written there apply every time.
- Never paste root passwords or API keys into the chat; use read-only deploy keys, CI secrets and a review of every diff before it reaches the deploy branch.
To deploy with Claude Code or Cursor, let the AI agent do what it is good at, changing the repository, and let your server deploy from Git. Ask the agent to make the app listen on $PORT, read its settings from environment variables, define build and start commands, add a health check route and keep secrets out of Git; give it the hosting platform's docs; then review its diff and push. The server deploys on push through a signed webhook, or your CI pipeline triggers the deploy with an API token, and the agent never needs your root password.
This guide is about the workflow and its safety, not about one framework. For framework details see deploying Node.js to a VPS, Python apps on a VPS or Next.js without Vercel. Claude Code and Cursor behaviour below comes from their official docs at the time of writing (November 2026).
What does "deploy with Claude Code" actually mean?
There are two ways to let an AI coding agent deploy, and only one of them is a good idea:
| Agent logs into the server | Agent pushes to Git, the server deploys | |
|---|---|---|
| What the agent needs | SSH access, often root, or a panel password | Your normal Git access on your own machine |
| What a mistake costs | Anything on the server: files, databases, other sites | A bad commit, which a health check or a rollback catches |
| Audit trail | Shell history, if any | Every change is a commit you can read and revert |
| Repeatable | Depends on what the agent typed this time | The same pipeline runs for every push |
Claude Code and Cursor can both run shell commands, so the first column is technically possible. It also means a language model with a prompt in front of it holds the keys to production. The second column keeps the agent in the repository, where its work is reviewable, and leaves the deploy to a pipeline that behaves the same every time.
Step 1: Give the agent the platform's docs
Agents guess when they do not know the target. A deploy that "should work on any VPS" often fails on details such as which address to bind, which variable carries the port, or whether the platform runs npm ci or npm install. The fix is to hand the agent the platform's own documentation.
Many platforms now publish their docs for language models using the llms.txt convention. ZoPanel publishes two files, described on its developers page:
- /llms.txt: an index of the documentation with one-line summaries and a Markdown link to each page;
- /llms-full.txt: the whole documentation in one Markdown file.
The full file is large (around 2 MB at the time of writing), so for a single deploy it is usually better to let the agent read the index and the two or three pages it needs, such as https://zopanel.net/docs/git-deploy.md and https://zopanel.net/docs/nodejs.md.
A ready-to-paste prompt for Claude Code or Cursor:
Read https://zopanel.net/llms.txt, then the pages it links for Git deploy and
for this project's runtime (Node.js, Python, PHP, static sites or Docker).
Prepare this repository for ZoPanel Git deploy:
1. Make the server listen on 127.0.0.1 and the port in the PORT environment variable.
2. Move every setting and secret to environment variables. Create .env.example
with the names and dummy values only, and make sure .env is in .gitignore.
3. Tell me the install, build and start commands ZoPanel will detect, and
change package.json or the Procfile if they would be wrong.
4. Add a health check route, for example GET /healthz returning 200, that does
not need a login or a database write.
5. Pin the runtime version (.nvmrc for Node.js).
6. List any folder the app writes to at runtime (uploads, cache) so I can set it
as a persistent path.
Do not read or print .env, do not run git push, and show me the diff when done.
In Claude Code, fetching a URL uses the WebFetch tool, which asks for approval per domain unless the domain is preapproved (permissions docs). In Cursor, the simplest reliable route is to paste the URLs into the prompt or download the pages into the repository and reference them as files.
Make the rules permanent with CLAUDE.md, AGENTS.md or Cursor rules
A prompt is forgotten in the next session. Both tools read instruction files from the repository:
- Claude Code loads a project
CLAUDE.md(or.claude/CLAUDE.md) at the start of every session and can import other files with@path/to/file. If the repository has anAGENTS.mdand noCLAUDE.md, Claude Code reads theAGENTS.md(memory docs). - Cursor reads
AGENTS.mdfrom the project root and subfolders, and project rules from.cursor/rules/*.mdc; a rule withalwaysApply: trueis used in every chat (rules docs).
One AGENTS.md therefore covers both tools:
# Deployment
- Production deploys from the `main` branch through ZoPanel Git deploy.
Platform docs: https://zopanel.net/llms.txt
- The server must listen on 127.0.0.1:$PORT. Never hard-code a port.
- Configuration comes from environment variables; .env.example lists them.
- GET /healthz must return 200 quickly without touching the database.
- Never read, print or commit .env or any key file.
- Work on a feature branch. Never push to main; I review and merge.
- Database migrations must stay backward compatible with the previous release.
Both vendors treat these files as guidance, not enforcement. Claude Code's docs say so directly and point to permission rules and hooks when something must be blocked.
Step 2: Have the agent prepare the repository
Whatever the platform, a repository that deploys cleanly has the same few properties. On ZoPanel each one maps to a documented setting in Git deploy:
| Requirement | Why | On ZoPanel |
|---|---|---|
Listen on 127.0.0.1:$PORT |
The platform picks the port and puts a proxy in front | PORT is set per blue/green slot, with HOST=127.0.0.1; a release that does not answer on it within 90 seconds fails |
| Settings in environment variables | Secrets stay out of Git; the same code runs in staging and production | Environment variables or Paste .env, available at build and runtime |
| Clear install, build and start commands | The platform must know how to build without you | Detected from the lock file, framework and Procfile; editable in Build & run |
| A lock file and a pinned runtime | Reproducible builds | npm ci with package-lock.json; Node.js version from .nvmrc, .node-version or engines.node |
| A health check path | Traffic should only move to a release that works | Set Health check path to /healthz; it must answer below 500 before the switch |
| Runtime files outside the release | Each deploy is a new folder | Persistent paths, for example uploads, .env |
A .gitignore for secrets |
The repository may be shared or public later | Not a platform feature; your job |
A minimal Express example of the first and fifth rows:
const express = require('express');
const app = express();
app.get('/healthz', (req, res) => res.status(200).send('ok'));
// ... your routes
const port = Number(process.env.PORT) || 3000;
app.listen(port, process.env.HOST || '127.0.0.1');
And a .gitignore the agent should add or extend:
.env
.env.*
!.env.example
*.pem
*.key
node_modules/
For Python, the start command binds the same way, for example gunicorn app:app --bind 127.0.0.1:$PORT (Python docs).
Step 3: Review the diff, then push
This is the step that makes AI-assisted deploys safe, and it takes a minute:
- Let the agent work on a feature branch (
git switch -c deploy-prep). - Read the diff yourself:
git diff main...deploy-prep. Look for hard-coded keys, a changed start command, deleted tests, new dependencies you did not ask for, and anything touching authentication. - Run the app locally with
PORT=4000 npm startandcurl -i http://127.0.0.1:4000/healthz. - Push the branch and merge it into the deploy branch yourself, through a pull request if you work in a team.
Because ZoPanel's webhook deploys only the configured branch, the agent can push feature branches freely without anything going live. The vibe coding security checklist has a longer list of what to check in AI-written code.
Step 4: Deploy on push with a signed webhook
The simplest pipeline: every merge to main deploys. On ZoPanel, open the website's Deploy tab, turn on Deploy when main is pushed, copy the Payload URL and Secret, and add them as a webhook in GitHub (content type application/json), GitLab or Gitea.
ZoPanel verifies GitHub's X-Hub-Signature-256 HMAC signature, or the token header for GitLab and Gitea, and never accepts the secret in the URL. Duplicate deliveries are ignored, at most one webhook deploy starts per 15 seconds, and none starts while another deployment is running. Each deploy builds in a new release folder inside the account's CPU and memory limits; the new release must pass its health check before nginx switches to it, and the last 5 releases stay available for a one-click rollback. The auto deploy from GitHub guide explains why each of these checks matters.
For a private repository, use a deploy key instead of a personal token: ZoPanel shows a public key under Deploy → Deploy key (private repositories), and you add it to the repository as a read-only key. On GitHub, deploy keys are read-only by default and tied to one repository (GitHub docs).
Option: trigger the deploy from CI with an API token
If you want tests to pass before anything deploys, let CI trigger the deploy instead of the webhook. With a paid (Pro) license, create a token in My account → API tokens and store it as a repository secret, never in the code or the chat. GitHub Actions secrets are referenced as ${{ secrets.NAME }}:
name: test-and-deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
- run: npm ci
- run: npm test
- name: Trigger ZoPanel deploy
run: |
curl -fsS -X POST \
-H "Authorization: Bearer ${{ secrets.ZOPANEL_TOKEN }}" \
"https://panel.example.com:8888/api/sites/${{ secrets.ZOPANEL_SITE_ID }}/app/deploy"
Use either the webhook or the CI trigger for a website, not both, or a push deploys before its tests finish. The agent can write this workflow for you; you add the secret in the repository settings yourself.
How do you keep secrets away from the AI agent?
The agent sees everything you paste and, depending on its permissions, every file it can open. Rules that hold for any tool:
- Never paste root passwords, panel passwords, API tokens or private keys into the chat. Put them in the platform's environment variables or in CI secrets, where the agent does not need them.
- Use deploy keys, not personal tokens, for the server's access to the repository. A read-only key for one repository limits the damage if it leaks.
- Block secret files in the tool. In Claude Code, add a
Read(./.env)deny rule in.claude/settings.json(permissions docs); By default Claude Code also asks before file edits and most shell commands. Cursor ignores files listed in.gitignore, its default list (which includes.env*) and.cursorignore, but its docs warn that protection is not guaranteed and that terminal and MCP tools can still read ignored files (ignore files docs). - Keep the agent off the deploy branch. It pushes feature branches; you merge.
- Review every diff, and rotate any secret that ever appeared in a commit, even one you deleted later.
Deploy it with ZoPanel
ZoPanel is a hosting panel you install on your own VPS. For an agent-built app it gives you the pipeline described above:
- Git deploy with framework detection for Next.js, Vite, Nuxt, SvelteKit, Express, Django, FastAPI, Flask, Laravel and more, sandboxed builds, health-checked zero-downtime releases and rollback (Git deploy docs);
- signed push webhooks for GitHub, GitLab and Gitea, and CI deploys with an API token on a paid license;
- llms.txt and llms-full.txt so Claude Code or Cursor can read the docs;
- databases, free SSL and logs in the same panel, plus an optional in-panel AI assistant that answers questions about your sites using your own Anthropic API key and runs actions only after you confirm.
What it does not have: there is no MCP server for ZoPanel, so the agent works through Git and the documented API rather than controlling the panel directly. There are no preview deployments and no global CDN, and you run the server. More on the workflow is on the vibe coding page.
Conclusion
Deploying with Claude Code or Cursor works best when the agent never touches the server: it prepares the repository against the platform's own docs, you review the diff, and Git triggers a deploy that is health-checked and reversible. Write the rules once in AGENTS.md, keep secrets in environment variables and CI secrets, and use read-only deploy keys.
To try it end to end, install ZoPanel's Free plan (10 websites, 10 databases, 3 hosting accounts) on a test VPS, paste the prompt above into your agent and push the result.
FAQ
Can Claude Code deploy my app to a server by itself?
It can run shell commands, so it could SSH into a server if you gave it access. It is safer not to: let it prepare the repository and push a branch, and let the server deploy from Git with a health check and rollback.
How do I give Cursor or Claude Code my hosting platform's documentation?
Point it at the platform's llms.txt file or at specific Markdown pages, either in the prompt or in AGENTS.md. ZoPanel publishes /llms.txt (an index) and /llms-full.txt (all docs in one file).
Should I put my server password in CLAUDE.md or AGENTS.md?
No. These files are committed to the repository and loaded into the model's context. Keep secrets in the platform's environment variables or in CI secrets, and keep .env in .gitignore.
Does ZoPanel have an MCP server?
No. Coding agents work with ZoPanel through Git deploy, push webhooks, the API with a token, and the documentation in llms.txt.
What if the AI agent breaks production?
On ZoPanel, a release that fails its health check never receives traffic, and the previous release keeps serving. If a release passes but behaves badly, roll back to one of the last 5 releases from the Releases card without downtime.
Put your servers on ZoPanel
Start free with 10 websites on a fresh Ubuntu or Debian server, or talk to our team about moving from cPanel, DirectAdmin or aaPanel and about licences for your business.
Free for 10 websites · No credit card · Installs in minutes
Keep reading

Vibe coding security checklist: secure AI code before deploy
A vibe coding security checklist for AI-generated apps: secrets, auth, database access, dependencies, deploy config, server isolation, monitoring and rollback.

What is vibe coding? Tools, limits and getting to production
What is vibe coding: where the term comes from, how it works, the main vibe coding tools, their limits, and how to take a vibe-coded app to production.

Deploy a Bolt.new, v0 or Replit app to your own server
How to deploy a Bolt.new, v0 or Replit app to your own VPS: export the code, fix what breaks outside the tool, then add a domain, SSL and auto deploy.