Overview
Zeabur builds and hosts services from a Git repository, a local directory or a Docker image. Its builder, zbpack, analyses the source (language, framework, package manager) and produces a container image without a Dockerfile. Databases, queues and apps come from a template marketplace, and the dashboard, CLI and public GraphQL API all drive the same backend. The CLI (zeabur, currently marked beta by its README) is run with npx zeabur; it was checked here at version 0.24.0.
Instructions
CLI
# log in: browser flow, or an API key created in the dashboard
npx zeabur auth login
npx zeabur auth login --token "$ZEABUR_TOKEN"
# create a project in a region, then deploy the current directory
npx zeabur project create --name shop-api # asks for the region; `project create --help` shows -r/--region
npx zeabur deploy --create --name shop-api --project-id 66a1c0ffee1234567890abcd
# redeploy an existing service
npx zeabur deploy --service-id 66a1c0ffee1234567890abce --environment-id 66a1c0ffee1234567890abcf
Useful commands (all take --help; add -i=false or the full flags for scripts and CI, and --json for machine-readable output):
npx zeabur project list
npx zeabur context set project --name shop-api # later commands reuse this context
npx zeabur service list
npx zeabur service restart --name shop-api --env-id 66a1c0ffee1234567890abcf
npx zeabur deployment log -t build --service-name shop-api --env-id 66a1c0ffee1234567890abcf
npx zeabur deployment log -t runtime --service-name shop-api --env-id 66a1c0ffee1234567890abcf -w
npx zeabur variable create --name shop-api --env-id 66a1c0ffee1234567890abcf -k NODE_ENV=production -y
npx zeabur variable env --env-id 66a1c0ffee1234567890abcf --name shop-api -f .env # OVERWRITES the service's variables from a .env file
npx zeabur variable list --name shop-api --env-id 66a1c0ffee1234567890abcf
npx zeabur domain create --name shop-api --env-id 66a1c0ffee1234567890abcf --domain api.shopfront.dev -y
npx zeabur template search postgres
There is no zeabur env or zeabur domain add command; variables live under variable (alias var) and domains under domain create. Other top-level commands: service exec, service port-forward, service metric, template deploy, upload, server, workspace (switch between personal and team accounts) and api graphql.
Build and start configuration
zbpack reads an optional zbpack.json in the repository root (keys are snake_case). Each key can also be set as a service environment variable with the ZBPACK_ prefix and upper-case name.
{
"build_command": "pnpm run build",
"start_command": "node dist/server.js",
"app_dir": "apps/web",
"cache_dependencies": false
}
zbpack.NAME.json, where NAME is the service name, overrides the defaults for one service; useful in monorepos (for examplezbpack.api.json).- In a pnpm or Yarn workspace Zeabur deploys the first Node.js app it finds; set
app_dir(ZBPACK_APP_DIR) to pick another. Nx and Rush monorepos are not auto-detected. - A
Dockerfilein the repository is used instead of auto-detection. - To preview what zbpack decides locally you need its own CLI (Go, plus buildkit); normally read the build log instead.
Frameworks and services
Detection covers Node.js (Next.js, Nuxt, Remix, SvelteKit, NestJS, Express, Astro, Vite and others, with npm, Yarn, pnpm and Bun), plus Python, Go, Rust, Java, PHP, Ruby and static sites; the per-language guides in the docs list the current set. Pushing to the connected GitHub branch triggers a new deployment. Add databases and other apps from the marketplace inside the same project; a service exposes its connection values as variables (such as a host and PORT), and you reference them from another service with ${VARIABLE_NAME}. Read the exact names on the database service's Variables tab rather than guessing.
Health checks and resources
By default Zeabur probes the exposed port over TCP (every 10 s, 5 s timeout, 3 failures). A custom HTTP path (for example /healthz) is set in the service Settings, and the app must return 2xx there. A failed health check leaves the previous deployment serving. Services with a volume use a recreate strategy, so expect brief downtime. CPU and memory are changed in Settings and apply on the next deployment; billing follows the allocation.
GraphQL API
Create an API key in the dashboard and send it as a Bearer token to https://api.zeabur.com/graphql. The schema is only available from the Apollo Explorer after login, so explore it there or use npx zeabur api graphql. Keys belong to a person, not a team; queries on team resources take an ownerID argument.
const res = await fetch("https://api.zeabur.com/graphql", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.ZEABUR_API_KEY}`,
},
body: JSON.stringify({ query: "query { me { username } }" }),
});
const { data, errors } = await res.json();
if (errors) throw new Error(errors[0].message);
console.log(data.me.username);
Examples
Example 1: Deploy a Next.js app from the terminal
User request: "Deploy this Next.js storefront to Zeabur and give it the DATABASE_URL from our Postgres."
export ZEABUR_TOKEN=... # API key from the dashboard, never committed
npx zeabur auth login --token "$ZEABUR_TOKEN"
npx zeabur project list --json
npx zeabur deploy --create --name storefront --project-id 66a1c0ffee1234567890abcd
npx zeabur variable create --name storefront --env-id 66a1c0ffee1234567890abcf -k 'DATABASE_URL=postgresql://${POSTGRES_USERNAME}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DATABASE}' -y # names as shown on the Postgres Variables tab
npx zeabur deployment log -t build --service-name storefront --env-id 66a1c0ffee1234567890abcf
The deploy command uploads the directory, zbpack picks the Next.js plan, and the log shows the build. The service gets a generated *.zeabur.app domain; domain create attaches your own.
Example 2: Deploy one app of a pnpm monorepo
User request: "Our Turborepo has apps/docs and apps/web; Zeabur keeps deploying docs."
Add zbpack.json to the repository root:
{ "app_dir": "apps/web" }
Commit and push; the next deployment builds apps/web. For a second service from the same repository use zbpack.api.json named after that service so each gets its own commands.
Guidelines
- Let detection work; add
zbpack.jsonor a Dockerfile only when the build log shows it chose wrongly. - Do not invent flags: run
npx zeabur <command> --help, the CLI is still beta and changes. - Keep API keys in environment variables or CI secrets, never in the repository.
- Use marketplace databases instead of running your own, and check their backup options in the service page before relying on them.
- Listen on the
PORTZeabur injects; if the port never accepts connections the deployment fails its health check. - A service with a volume cannot do zero-downtime deploys.