Resource Management

Zapper names the resources it creates so they can be discovered later:

• Native processes and Docker containers: zap.<project>.<instanceId>.<service>
• Generated Docker volumes: zap.<project>.<instanceId>.volN

For the proposed machine-wide project registry and dashboard model, see Global Registry Design.

zap ls shows configured services and assigned ports by default. Use zap ls --extended (or zap ls --all) for the local inventory view: configured services first, then recognized instances from the local .zap/state.json and resources that look related to the project but no longer line up with the current config or state.

Resource Types

Current resources

Current resources belong to the selected instance and still match a service or managed volume path in the current zap.yaml.

Dangling resources

Dangling resources belong to an instance recorded in this repo, but no longer match the current zap.yaml or current state. Common causes:

• A service was renamed or removed while its native process or Docker container still exists.
• A generated Docker volume exists but is no longer tracked in .zap/state.json.
• A managed volume path changed, leaving the old generated volume assignment stale.

Use zap ls --extended to see these. The usual repair is to stop/delete the stale resources rather than hand-editing state.

Unrecognized resources

Unrecognized resources match the current project name but do not belong to any instance recorded in the local .zap/state.json. They usually come from another checkout, older state, or manual resource creation.

Use zap global list (or zap global ls, zap g ls) for a machine-wide view of discovered Zapper native and Docker container resources. Use zap global kill <project> when you want project-wide cleanup across checkouts.

Cleanup Commands

• zap down stops resources for the selected instance and current config.
• zap kill deletes all native processes and Docker containers for the current project across instances.
• zap global kill <project> deletes native processes and Docker containers for a named project.
• zap global prune audits stale registry entries and orphaned resources before mutating anything. After confirmation, it deletes orphaned native processes, Docker containers, and generated Docker volumes, then removes stale registry entries. Use --force (-y) for non-interactive cleanup.
  • The audit only judges a running native process or container "dangling" when its owning project loads successfully and no longer lists that service. If a registered project cannot be loaded right now (invalid config, missing dependency, mid-edit), its live resources are left alone rather than offered for deletion, so a temporarily broken project is never pruned out from under you.
• zap volume prune deletes stale generated Docker volumes for the selected instance.
• zap volume reset forgets generated volume assignments in .zap/state.json without deleting Docker volumes.

For one-off cleanup, Docker and Zapper cleanup commands are still valid escape hatches:

docker rm -f <container>
docker volume rm <volume>
zap kill

Practical Recovery

If a config change leaves old resources around:

zap ls --extended
zap volume prune
zap kill
zap up

If generated volume state is confusing but you want to keep the Docker volumes for manual inspection:

zap volume reset
zap init