Existing projects

Ant manages what it deploys. Workloads that already exist on a machine are left alone: they are not listed, stopped, pruned, or adopted automatically. There are three ways to bring something existing under management, one recipe for a hand-managed compose stack, and one supported exit.

From existing source

ant nest init writes ant.yaml for the project in the current directory and auto-detects the build and run from the files present:

ant nest init
ant nest init --build none --file docker-compose.yml   # explicit

Override with --build, --run, and --file; --force overwrites an existing ant.yaml. Then ant haul builds and ant trail deploy runs it, locally, or on a registered machine through the deployment's server:. Remote deploys ship the project context, so the source does not need to exist on the target machine.

Review the result before deploying: env, secrets, and domains are yours to add (ant nest edit env, ant nest edit secret, ant nest edit domain).

From an existing image

ant trail deploy --image runs a prebuilt image as an Ant-managed container on a registered machine:

ant trail deploy --image ghcr.io/acme/api:1.4.2 --machine prod --pull \
  --port 8080 --env LOG_LEVEL=info --domain api.example.com

--from-tar uploads a docker save archive instead of pulling. The container carries Ant's labels, so it appears in ant nest containers list and the dashboard's Docker tab, takes logs, and can be started, stopped, or removed like any other Ant workload. The dashboard's Run image action on a machine is the same path.

Onboarding an existing machine

ant nest machines add plus ant nest bootstrap install the worker without touching what is already running. Re-running bootstrap is the upgrade path and preserves the machine identity and roster.

ant nest machines add prod --host 173.87.3.89 --ssh-key ~/.ssh/id_ed25519
ant nest machines add prod --node-id 7f2e…          # worker already running
ant nest doctor --machine prod                      # host checks
ant nest tools                                      # builders and helpers on the machine

ant nest reconcile --apply is the operator-run root path for privileged host setup (exact argv, no shell; see Security model). Ant programs the Caddy it manages; a Caddy the machine already runs for other workloads is detected, not reconfigured.

Cutover: an existing compose stack

Ant does not adopt a running compose project. Resource names are derived (<group>-<app>-<env>-<branch>), so a hand-managed stack with a different name is never matched, replaced, or removed; a deploy would create a parallel stack and fail loudly on port conflicts rather than clobber.

To take one over deliberately:

1. Scaffold from the same source. ant nest init --build none --file docker-compose.yml, then set app and review ports, volumes, and domains.
2. Handle data. Bind mounts keep working unchanged. Named volumes are owned by the compose project, so either declare the old ones external: true in the compose file (Docker reuses them as-is) or accept Ant-namespaced volumes and migrate the data.
3. Stage, then cut over. Run on different host ports first to verify, then stop the old stack and ant trail deploy. Zero-downtime staging happens within one deployment; it does not span two different stacks, so expect a short gap at this step.
4. Move the routing. If the machine has an external proxy, either add the hostnames to Ant's Caddy (ant nest edit domain add) or keep routing outside and deploy with --no-caddy.

What stays out of scope

Existing workloads are not addressable through Ant's surfaces, by design:

• ant nest containers lists, controls, and reads logs for Ant-managed containers only; unmanaged names are refused.
• ant nest volume list hides unmanaged volumes unless --all is given, and removal refuses them without --all.
• Pruning removes only what it can positively identify as Ant-managed; unknown projects and containers are always kept.
• ant nest tunnel forwards to Ant-managed containers.

This is what keeps a shared machine safe: Ant cannot accidentally stop, prune, or reconfigure somebody else's stack.

Leaving

ant nest machines decommission --host ADDR --handover --yes exports a plain-compose takeover bundle to ~/ant-handover on the machine, so the workloads keep running without Ant. There is no import for that bundle back into Ant; re-onboard with the source or image paths above.