---
name: zerops-operate
description: Inspect and maintain running Zerops services with zcli and the GUI. Use for logs, environment changes, lifecycle operations, scaling, public access, deletion, and diagnosis of build or runtime failures.
---

# Operate Zerops services

## Establish the target

1. Use the `zerops-setup` skill for installation, browser login, organization/project
   selection, and region problems. Use zcli v1.1.3 or newer; verify with `zcli version`.
   Never request tokens in chat or inspect CLI credential files. Reserve `ZEROPS_TOKEN`
   for an already provisioned CI/headless environment.
2. Identify the exact project and service before a change. List their status:

   ```sh
   zcli project list
   zcli service list --project-id PROJECT_ID
   ```

   Replace uppercase placeholders with verified IDs/names. Service operations below
   use `--service-id` to avoid selectors. Confirm that ID in the intended project's
   list; adding a project flag to a service-ID command does not validate membership.
3. Record the failing app version/pipeline, symptom and relevant time window. A healthy
   old version can keep a service active while a new deployment fails. Inspect the
   target pipeline in the GUI, not just the service status.
4. Use the user's requested operation as the scope. These workflows need a shell and
   public HTTPS access, not VPN, SSH or a Zerops container. When a step needs the GUI,
   use an authorized browser session or give the user the precise steps and await
   their result. Do not claim to have performed a GUI-only change from the shell.

Commands here are checked against [zcli v1.1.3 source](https://github.com/zeropsio/zcli/tree/v1.1.3/src/cmd).
There is no standalone status command, env setter, restart, scaling or custom-domain
command in that release. For a different version, check `zcli service --help` or
`zcli project --help` before using an unfamiliar operation.

## Inspect logs

Start with a bounded snapshot; treat logs as potentially secret-bearing and report
only the relevant sanitized error, phase and timestamp. Do not paste raw logs into
chat or commit them.

```sh
# Runtime logs
zcli service log --service-id SERVICE_ID --limit 100 --format json

# Latest app-version's build logs
zcli service log --service-id SERVICE_ID --show-build-logs --limit 100 --format json

# Live runtime stream; stop the stream when the observation is complete
zcli service log --service-id SERVICE_ID --follow --format jsonstream

# Severity and source filter
zcli service log --service-id SERVICE_ID --minimum-severity ERROR --message-type APPLICATION --limit 100 --format json
```

- Use singular `log`. Valid formats are `FULL`, `SHORT`, `JSON`, `JSONSTREAM`
  (case-insensitive); `--follow` cannot use `JSON`. Build logs can also follow with
  `--show-build-logs --follow --format jsonstream` and the explicit service ID.
- Use `--message-type WEBSERVER` for webserver logs. Limits are 1–1000 entries.
  Severity filtering depends on syslog severity; ordinary stdout/stderr may appear
  as info, so retry without the severity filter before concluding there are no errors.
- There is **no `--since` or text-search flag** in v1.1.3. For a requested “since”
  window, use the GUI's time-period filter. A filtered local snapshot contains only
  the fetched entries; do not present it as complete time-range history.
- Open service **Runtime logs** or **Database logs** for per-container selection,
  severity and time-period filters. Use project **Logs overview** or **Go to full
  service log** for combined logs.
- Open service **Pipelines & CI/CD settings → Pipeline detail** for the selected
  version's build and prepare-runtime logs. The CLI build option selects the latest
  app version, not an arbitrary older build. Historical prepare-runtime logs have no
  dedicated CLI retrieval command. “No build was found” or an uploading-state error
  is not proof of an application crash.

Sources: [log command](https://github.com/zeropsio/zcli/blob/v1.1.3/src/cmd/serviceLog.go),
[log validation](https://github.com/zeropsio/zcli/blob/v1.1.3/src/serviceLogs/handler_checkInputValues.go),
[GUI logs](https://docs.zerops.io/references/logging).

## Read and change environment configuration

Use a key-only template for an inventory in the application's service context:

```sh
zcli project env --project-id PROJECT_ID --service SERVICE_NAME --template '{{.Key}}'
```

`--service` takes the service **name**, not ID. Add `--user-only` when only user keys
are relevant. The default output includes values; avoid it for routine diagnosis.
Do not use `--export` with the key-only template: it overrides the template.
`--reveal` exposes sensitive values and requires Zerops sudo mode; it is unnecessary
for checking names. Keep any value inspection private and never print credentials.
`zcli env` describes the CLI environment; it does not manage application variables.

1. Identify the owner of the setting: project Shared vault, service vault, generated
   dependency variable, or `build.envVariables` / `run.envVariables` in `zerops.yaml`.
2. Set existing stored values in the appropriate project/service GUI vault controls;
   mark secrets sensitive. There is no zcli env setter. Have the user enter new secrets
   in the GUI rather than chat. Use `zerops-import` for initial infrastructure/vault
   configuration, not an improvised import overwrite to edit an existing service.
3. Use `zerops-yaml` to map stored values to application keys explicitly, for example
   `APP_SECRET: ${APP_SECRET_VALUE}` or `DATABASE_URL: ${db_connectionString}` when
   the database service is actually named `db`. Keep vault and application key names
   distinct: `KEY: ${KEY}` can remain unresolved. A missing reference can remain
   literal `${NAME}`. Never commit actual secrets in YAML.
4. Restart affected consuming services after changing stored values. Running processes
   retain their startup environment; reload alone is insufficient. Do not assume a
   GUI edit has restarted every consumer: verify its outcome.
5. Redeploy after changing YAML environment mappings/literals. Rebuild and deploy
   when a value is embedded in build output, such as frontend configuration. A runtime
   restart cannot rewrite built assets. Follow `zerops-deploy` for the deployment.
6. Verify application behavior and sanitized logs, not just the presence of a key in
   the project inventory. Under service isolation, sibling values require explicit
   references. Do not weaken isolation or expose a database publicly to fix a mapping.

Sources: [env command](https://github.com/zeropsio/zcli/blob/v1.1.3/src/cmd/projectEnv.go),
[environment lifecycle](https://docs.zerops.io/guides/environment-variables).
Use current vault/reference guidance in [diagnosis notes](references/diagnosis.md)
when older docs show legacy env-store names.

## Start, stop and restart

```sh
zcli service start --service-id SERVICE_ID
zcli service stop --service-id SERVICE_ID
```

Run only the requested action; these are alternatives, not a sequence to paste.
Both wait for the platform operation. For restart, use the service's restart action
in the GUI; exact control placement may change. zcli v1.1.3 has no restart command.
Use stop followed by start only when that interruption is acceptable within the
user's request; it is not a rolling-restart promise.

After completion, check the service list, runtime logs and the relevant application
response. Interrupted waiters can exit successfully without proving completion.
For project-wide lifecycle changes, use the GUI and inspect affected services.

Sources: [start](https://github.com/zeropsio/zcli/blob/v1.1.3/src/cmd/serviceStart.go),
[stop](https://github.com/zeropsio/zcli/blob/v1.1.3/src/cmd/serviceStop.go),
[lifecycle permissions](https://docs.zerops.io/features/rbac).

## Scale an existing service

Use service **Automatic scaling configuration** in the GUI; zcli has no scaling
command. Inspect CPU, RAM, disk and container history before changing bounds.
Adjust vertical resource bounds or runtime container bounds to the observed need;
explain the resource/cost change. Use the current service type's allowed values,
not a universal limit copied from another runtime.

For memory spikes at startup, inspect minimum RAM and minimum free RAM as well as
the maximum. Check for leaks. Before adding runtime containers, ensure sessions and
persistent state work across instances. Managed databases do not use ordinary runtime
horizontal scaling; inspect their topology/profile controls. Docker resource changes
can restart its VM. Use `zerops-import` for authoring new infrastructure bounds.

Sources: [scaling controls and metrics](https://docs.zerops.io/features/scaling),
[service-specific scaling](https://docs.zerops.io/guides/scaling).

## Configure subdomains and custom domains

For generated subdomain setup or recovery, follow [Activate and verify public
access](../zerops-deploy/SKILL.md#activate-and-verify-public-access) in
`zerops-deploy`, including its bounded URL check.

Retrieve the actual URL in service **Subdomain & domain & IP access**; do not construct
it from a hostname. Each declared HTTP-supporting port receives its own URL. Check
the app's listener matches its declared port. Change its bind setting only when
it explicitly uses `localhost`, `127.0.0.1` or `::1`, or the framework's documented
default is loopback-only; otherwise leave the code alone. [Node's `listen(port)`
without a host](https://nodejs.org/api/net.html#serverlistenport-host-backlog-callback)
already listens on all interfaces (`::` or `0.0.0.0`). Use `zerops-yaml` to correct
`run.ports` / `httpSupport`. To disable subdomain access, use the GUI toggle; there
is no CLI disable command. Generated URLs use HTTPS with platform-managed TLS.

For custom domains, use the same GUI section (or project access overview):

1. Add the exact domain names and select certificate management. Map each source
   path to the intended service and internal HTTP port. Use the displayed project IPs
   or CNAME target; never copy example addresses or infer them from a generated URL.
2. At the user's DNS provider, apply the appropriate records:

   | Routing choice | DNS records |
   | --- | --- |
   | Shared IPv4, DNS only | `A` to the shared IPv4 **and** `AAAA` to the project's IPv6; both are required. |
   | Dedicated IPv4, DNS only | `A` to the project's dedicated IPv4; optionally `AAAA` to its IPv6. |
   | CNAME | Use the GUI-provided project CNAME target for a subdomain, or apex only if the provider supports flattening. |

3. For a proxy/CDN, follow the provider-specific docs. With proxied CNAME, exclude
   shared IPv4 using the GUI option; proxying shared-IPv4/AAAA combinations can break
   routing. Do not prescribe DNS-only shared-IP records as a proxied setup.
4. Verify DNS, certificate issuance, route/port and the expected HTTPS response.
   Zerops manages Let's Encrypt installation/renewal when selected. Report DNS or
   certificate propagation as pending until observed; a saved form is not proof.

Sources: [public access](https://docs.zerops.io/references/networking/public-access),
[DNS records and proxy rules](https://docs.zerops.io/references/networking/dns),
[Cloudflare](https://docs.zerops.io/references/networking/cloudflare).

## Diagnose before changing resources

Read [the diagnosis table](references/diagnosis.md) for build failures, missing
artifacts, crashes, port/bind errors, readiness, missing env, database errors, OOM
and 502 responses. Fix the owning source/configuration and use `zerops-deploy` to
redeploy when needed. Do not delete infrastructure as a troubleshooting shortcut.

## Delete only after explicit confirmation

Always confirm with the user immediately before deletion. Show the organization,
project/service names and IDs, and affected services/data. For project deletion,
enumerate its services first. Establish whether required data has a recoverable
backup. Do not treat an earlier diagnosis or cleanup request as deletion confirmation.

After confirmation, run only the approved command:

```sh
zcli service delete --service-id SERVICE_ID --confirm
# Or, for the confirmed whole project:
zcli project delete --project-id PROJECT_ID --confirm
```

`--confirm` skips the CLI prompt; it does not replace user confirmation. Re-list the
project or services to verify removal. Report the actual result and any failed or
unfinished operation.

Sources: [service deletion](https://github.com/zeropsio/zcli/blob/v1.1.3/src/cmd/serviceDelete.go),
[project deletion](https://github.com/zeropsio/zcli/blob/v1.1.3/src/cmd/projectDelete.go).