Skip to main content
DELETE
/
api
/
stacks
/
{name}
curl -X DELETE "https://your-dockhand-instance.com/api/stacks/my-app?env=1" \
  -H "Cookie: auth_token=your_token"

{
  "success": true
}

​
Path Parameters

​
name
string
required
Stack name (URL-encoded)

​
Query Parameters

​
env
string
required
Environment ID where the stack exists
​
force
boolean
default:false
Force deletion without confirmation. Removes containers, networks, volumes, and files.

​
Response

​
success
boolean
Whether the deletion succeeded
​
error
string
Error message if deletion failed

​
Behavior

  • Stops and removes all containers in the stack
  • Removes networks created by the stack (if not in use by other containers)
  • Removes named volumes (when force=true)
  • Deletes compose file, .env file, and stack directory
  • Removes stack from database
  • For Git stacks, also removes Git repository clone and unregisters auto-sync schedule

​
Deletion Process

  1. Runs docker compose down (with -v flag if force=true)
  2. Deletes compose file and environment file
  3. Removes stack directory
  4. Removes database records (stack sources, environment variables)
  5. For Git stacks: removes repository clone and schedules
curl -X DELETE "https://your-dockhand-instance.com/api/stacks/my-app?env=1" \
  -H "Cookie: auth_token=your_token"

{
  "success": true
}

​
Force Delete vs Standard Delete

Standard Delete

  • Stops containers
  • Removes containers
  • Removes networks (if unused)
  • Preserves volumes
  • Deletes compose files

Force Delete

  • Stops containers
  • Removes containers
  • Removes networks (if unused)
  • Removes volumes
  • Deletes compose files

​
Important Notes

Force deletion (force=true) permanently removes all volumes associated with the stack. This includes databases, uploaded files, and any persistent data. This action cannot be undone.
Networks are only removed if they are not in use by other containers. Shared networks will be preserved.
External stacks (adopted stacks) only have their Dockhand metadata removed. The actual compose files at the external location are not deleted.

​
What Gets Deleted

​
Internal Stacks (Created via Dockhand)

  • All containers
  • All networks (if unused)
  • All volumes (if force=true)
  • Compose file at /data/stacks/{name}/compose.yaml
  • Environment file at /data/stacks/{name}/.env
  • Stack directory at /data/stacks/{name}/
  • Database records

​
Git Stacks

  • All containers
  • All networks (if unused)
  • All volumes (if force=true)
  • Git repository clone at /data/git-repos/repo-{id}/
  • Database records
  • Auto-sync schedules

​
External Stacks (Adopted)

  • All containers
  • All networks (if unused)
  • All volumes (if force=true)
  • Database records only
  • Original files are NOT deleted

​
Error Responses

​
400 Bad Request

{
  "success": false,
  "error": "Stack is currently running. Stop it first or use force=true"
}

​
403 Forbidden

  • User lacks stacks:remove permission
  • User cannot access the specified environment

​
404 Not Found

{
  "error": "Compose file not found for stack \"my-app\". The stack may have been deleted or was created outside of Dockhand."
}

​
500 Internal Server Error

  • Docker daemon error
  • File system error
  • Database error

​
Permissions

Requires stacks:remove permission for the specified environment.

Build docs developers (and LLMs) love

Get started for freeTalk to us