# 1. Create an access token and install zCLI

Before you start, create an access token and install zCLI so your local machine can work with your Zerops account.

• Open Access Token Management in the Zerops Dashboard: https://app.zerops.io/settings/token-management
• Create a new personal access token and copy it immediately.
• Install zCLI:

npm i -g @zerops/zcli

• Log in with your token:

zcli login <personal-access-token>

If you do not use npm, check the zCLI documentation: https://docs.zerops.io/references/cli

# 2. Start the VPN

To reach private databases or services from your local machine, open a secure tunnel into the project network.

• Run:

zcli vpn up

• Select your project from the list.
• Keep the VPN connection active while working locally.
• Use internal hostnames such as db, redis, or api.

# 3. Find your service name

Many commands need the exact name of your service. You can find it in the Zerops Dashboard.

• Open your project in the Zerops Dashboard.
• In the project overview, find the service you want to manage.
• Use this exact name whenever a command asks for <service-name>.

# 4. Download environment variables

Instead of copying values manually, export your service configuration into a local .env file.

• Export only user-defined variables:

zcli project env --service <service-name> --user-only > .env

• Remove --user-only if you also need system-generated variables.
• Add --export if you want the output to include the export keyword for shell sourcing.

# 5. Configure deployment pipeline

Decide how your code should reach the staging environment.

• In the Zerops Dashboard, go to Service Settings > Pipelines & CI/CD Settings.
• Connect your repository.
• Add a trigger so every push to your main branch starts a deployment automatically.
• If you prefer manual control, you can use zcli push later instead of Git triggers.

# 6. Develop and test locally

With the VPN active and your .env file ready, run your application locally while it connects to Zerops-hosted services.

Example PostgreSQL connection:

psql -h db -U user -d database

Example internal API check:

curl http://api:3000/health

# 7. Push your code changes

When local tests pass, deploy your changes to the staging environment.

If you configured Git triggers:

git add .
git commit -m "feat: implement new feature"
git push

If you prefer pushing directly from your machine:

zcli push <service-name>

# 8. Test your staging application

Verify the deployment before moving toward production.

• Open your application through the provided Zerops subdomain.
• Check runtime logs in the Zerops Dashboard under Service Settings > Runtime Logs.
• Confirm the app starts correctly and there are no deployment or runtime errors.